diff --git a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto index 6673e93..f1aebda 100644 --- a/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto +++ b/up-core-api/uprotocol/core/udiscovery/v3/udiscovery.proto @@ -42,26 +42,24 @@ service uDiscovery { // Used by any uProtocol application or service to find service instances // locations. The passed UUri contains valid UEntity, UResource, and UAuthority information // for a query. - // What is returned is a list of UUris that match the query. Possible return values in status are: - // 1. code.OK: Query lookup was successful + // What is returned is a list of UUris that match the query. + // If lookup fails, the response will be a UStatus with // 2. code.NOT_FOUND: No matching UUris were found // 3. code.INVALID_ARGUMENT: The passed UUri is invalid // 4. code.PERMISSION_DENIED: The caller does not have permission to perform the query - rpc LookupUri(v1.UUri) returns (LookupUriResponse) { + rpc LookupUri(LookupUriRequest) returns (LookupUriResponse) { option (uprotocol.method_id) = 1; } // Update a node in the database. - // What is returned is the status of the API request as uprotocol.v1.UStatus. // **NOTE:** You MUST have write permission to the node in the database - rpc UpdateNode(UpdateNodeRequest) returns (uprotocol.v1.UStatus) { + rpc UpdateNode(UpdateNodeRequest) returns (UpdateNodeResponse) { option (uprotocol.method_id) = 2; } // Query the database to find Node(s). What is passed is the search criterial in // the FindNodeRequest message. the returned FindNodeResponse contains the - // resulting query node(s) and their child nodes, as well as the - // uprotocol.v1.UStatus for the query. Below are some example queries: + // resulting query node(s) and their child nodes. Below are some example queries: // 1. uDomain: `//*.device/` // 2. uDevice: `//device` // 3. uService: `//device.domain/body.access/` @@ -77,19 +75,18 @@ service uDiscovery { } // Remove one or more nodes (and all its children nodes) in the database. - // What is returned is the status of the API request as uprotocol.v1.UStatus. // **NOTE:** You MUST have write permission to the deleted all the nodes passed, // all the children nodes, as well as write permission to the parent otherwise // you will get PERMISSION_DENIED and no nodes will be deleted. - rpc DeleteNodes(DeleteNodesRequest) returns (uprotocol.v1.UStatus) { + rpc DeleteNodes(DeleteNodesRequest) returns (DeleteNodesResponse) { option (uprotocol.method_id) = 5; } - // Add one of more nodes to a parent node. If one of the nodes already exists, this API will return - // ALREADY_EXISTS and none of the nodes shall be added to the parent. + // Add one of more nodes to a parent node. If one of the nodes already exists, this RPC will fail + // with a UStatus containing an ALREADY_EXISTS UCode and none of the nodes shall be added to the parent. // **NOTE:** You MUST have write permission to the parent node - rpc AddNodes(AddNodesRequest) returns (uprotocol.v1.UStatus) { + rpc AddNodes(AddNodesRequest) returns (AddNodesResponse) { option (uprotocol.method_id) = 6; } @@ -97,28 +94,28 @@ service uDiscovery { // Update a property in a node // **NOTE:** You MUST have write permission to the node who's property you // are updating - rpc UpdateProperty(UpdatePropertyRequest) returns (uprotocol.v1.UStatus) { + rpc UpdateProperty(UpdatePropertyRequest) returns (UpdatePropertyResponse) { option (uprotocol.method_id) = 7; } // Register to receive Notifications to changes to one of more Nodes. The changes // are published on the notification topic: '/core.udiscovery/3/nodes#Notification' - rpc RegisterForNotifications(NotificationsRequest) returns (uprotocol.v1.UStatus) { + rpc RegisterForNotifications(NotificationsRequest) returns (NotificationsResponse) { option (uprotocol.method_id) = 8; } // Unregister for Node change notifications - rpc UnregisterForNotifications(NotificationsRequest) returns (uprotocol.v1.UStatus) { + rpc UnregisterForNotifications(NotificationsRequest) returns (NotificationsResponse) { option (uprotocol.method_id) = 9; } // Resolve a UUri filling in the missing names/numbers from the Discovery database. // If the resolution was successful, the resolved UUri containing names and numbers - // is returned along with the following status.code values: - // - code.OK: Resolution was successfull + // is returned. + // If resolving fails, the response will be a UStatus with // - code.NOT_FOUND: Unable to find the missing names or numbers for the passed UUri // - code.INVALID_ARGUMENT: The passed UUri is invalid (missing names or numbers) // - code.PERMISSION_DENIED: The caller does not have permission to perform the resolution @@ -183,15 +180,19 @@ message UpdateNodeRequest { // Time-to-live: How long (ms) the information should be live for in the database. // -1 means lives forever - optional int32 ttl = 3; + optional int32 ttl = 2; } +// The (empty) response message representing the successful execution of the UpdateNode operation. +message UpdateNodeResponse {} // Delete one or more nodes request message DeleteNodesRequest { repeated string uris = 1; // uProtocol formatted URI } +// The (empty) response message representing the successful execution of the DeleteNodes operation. +message DeleteNodesResponse {} // FindNodesRequest passed to FindNodes() message FindNodesRequest { @@ -208,15 +209,13 @@ message FindNodesRequest { // FindNodesResponse that is returned from the FindNodes() API message FindNodesResponse { + // List of node information repeated Node nodes = 1; - // Return code for the rpc call - uprotocol.v1.UStatus status = 2; - // Time-to-live: How long (ms) the information should be live for in the database. // -1 means lives forever - optional int32 ttl = 3; + optional int32 ttl = 2; } @@ -235,9 +234,6 @@ message FindNodePropertiesRequest { message FindNodePropertiesResponse { // a list of property name/value pairs map properties = 1; - - // Return code for the rpc call - uprotocol.v1.UStatus status = 2; } @@ -253,6 +249,8 @@ message AddNodesRequest { repeated Node nodes = 2; } +// The (empty) response message representing the successful execution of the AddNodes operation. +message AddNodesResponse {} // Message passed to UpdateProperty() to update a property in a Node message UpdatePropertyRequest { @@ -266,6 +264,8 @@ message UpdatePropertyRequest { PropertyValue value = 3; } +// The (empty) response message representing the successful execution of the UpdateProperty operation. +message UpdatePropertyResponse {} // Node Change Notification Message. // When uEs call RegisterForNotifications(), a Notification message is sent when the node either @@ -323,24 +323,32 @@ message NotificationsRequest { optional int32 depth = 3; } +// The (empty) response message representing the successful execution of the +// RegisterForNotifications and UnregisterForNotifications operations. +message NotificationsResponse {} + // Request message passed to ResolveUri() API to resolve the missing names or numbers. message ResolveUriRequest { - // The URI to resolve containing only names or numbers - v1.UUri uri = 1; + // The URI to resolve + uprotocol.v1.UUri uri = 1; } -// Response message returned from ResolveUri() API containing a UUri and the -// status of the resolution. +// Response message returned from ResolveUri() API containing the resolved UUri message ResolveUriResponse { - v1.UUri uri = 1; // Resolved UUri - uprotocol.v1.UStatus status = 3; // Return code for the rpc call + // Resolved URI + uprotocol.v1.UUri uri = 1; } +// Request message passed to LookupUri() API. +message LookupUriRequest { + // The Uri to look up + uprotocol.v1.UUri uri = 1; +} // Return value from LookupUri() API that contains the batch of Uris for the -// lookup and status from the API call +// lookup message LookupUriResponse { - v1.UUriBatch uris = 1; // Batch of Uris - uprotocol.v1.UStatus status = 2; // Return code for the rpc call + // Batch of URIs + uprotocol.v1.UUriBatch uris = 1; } diff --git a/up-core-api/uprotocol/core/usubscription/v3/usubscription.proto b/up-core-api/uprotocol/core/usubscription/v3/usubscription.proto index 18c27ed..1484e43 100644 --- a/up-core-api/uprotocol/core/usubscription/v3/usubscription.proto +++ b/up-core-api/uprotocol/core/usubscription/v3/usubscription.proto @@ -54,7 +54,7 @@ service uSubscription { // The consumer no longer wishes to subscribe to a topic so it issues an // explicit unsubscribe request. - rpc Unsubscribe(UnsubscribeRequest) returns (uprotocol.v1.UStatus) { + rpc Unsubscribe(UnsubscribeRequest) returns (UnsubscribeResponse) { option (uprotocol.method_id) = 2; } @@ -66,12 +66,12 @@ service uSubscription { // Register to receive subscription change notifications that are published on the // 'up:/core.usubscription/3/subscriptions#Update' - rpc RegisterForNotifications(NotificationsRequest) returns (uprotocol.v1.UStatus) { + rpc RegisterForNotifications(NotificationsRequest) returns (NotificationsResponse) { option (uprotocol.method_id) = 6; } // Unregister for subscription change events - rpc UnregisterForNotifications(NotificationsRequest) returns (uprotocol.v1.UStatus) { + rpc UnregisterForNotifications(NotificationsRequest) returns (NotificationsResponse) { option (uprotocol.method_id) = 7; } @@ -87,7 +87,7 @@ service uSubscription { // reset). // **__NOTE:__** This is a private API only for uSubscription services, // uEs can call Unsubscribe() to flush their own subscriptions. - rpc Reset(ResetRequest) returns (uprotocol.v1.UStatus) { + rpc Reset(ResetRequest) returns (ResetResponse) { option (uprotocol.method_id) = 9; } } @@ -119,7 +119,7 @@ message SubscribeAttributes { message SubscriberInfo { // subscriber URI containig the names and numbers of the // uE subscribing. Example represented in long form: `//device.domain/com.gm.app.hartley` - v1.UUri uri = 1; + uprotocol.v1.UUri uri = 1; // Any additional device specific subscriber information repeated google.protobuf.Any details = 2; @@ -141,12 +141,11 @@ message SubscriptionStatus { // remote uSubscription Service } + reserved 2; + // Subscription state State state = 1; - // The Subscription status code - uprotocol.v1.UCode code = 2; - // The Subscription status message string message = 3; } @@ -171,7 +170,7 @@ message EventDeliveryConfig { // Passed to Subscribe() contains the subscription request information message SubscriptionRequest { // uProtocol uri topic to subscribe too - v1.UUri topic = 1; + uprotocol.v1.UUri topic = 1; // Subscribers's information (who is calling Subscribe) SubscriberInfo subscriber = 2; @@ -183,7 +182,7 @@ message SubscriptionRequest { // Response message from the Subscribe() API message SubscriptionResponse { - // Current status of the subscription (state, code, etc...) + // Current status of the subscription SubscriptionStatus status = 1; // Any platform (uDevice) specific additional event delivered configuration @@ -191,7 +190,7 @@ message SubscriptionResponse { EventDeliveryConfig config = 2; // Subscription topic passed to SubscriptionRequest - v1.UUri topic = 3; + uprotocol.v1.UUri topic = 3; } @@ -199,18 +198,20 @@ message SubscriptionResponse { // to as well as the subscriber identification message UnsubscribeRequest { // Topic to be unsubscribed to - v1.UUri topic = 1; + uprotocol.v1.UUri topic = 1; // Subscriber identification SubscriberInfo subscriber = 2; } +// The (empty) response message representing the successful execution of the Unsubscribe operation. +message UnsubscribeResponse {} // Passed to FetchSubscribers such that we can obtain a list of subscribers to // a particular topic message FetchSubscribersRequest { // Topic we wish to find the subscribers for - v1.UUri topic = 1; + uprotocol.v1.UUri topic = 1; // Offset in the fetch requests optional uint32 offset = 2; @@ -220,14 +221,12 @@ message FetchSubscribersRequest { // Returned from FetchSubscribers(), this message contains a repeated list of // SubscriberInfo message FetchSubscribersResponse { + reserved 3; // List of subscribers repeated SubscriberInfo subscribers = 1; // Set to true if the batch did not return all records optional bool has_more_records = 2; - - // Status of the query - uprotocol.v1.UStatus status = 3; } @@ -235,12 +234,12 @@ message FetchSubscribersResponse { // is returned from FetchSubscriptions() API. message Subscription { // Subscription topic - v1.UUri topic = 1; + uprotocol.v1.UUri topic = 1; // Information about the subscriber who changed their subscription SubscriberInfo subscriber = 2; - // Current status of the subscription (state, code, etc...) + // Current status of the subscription SubscriptionStatus status = 3; // Subscribers subscription attributes @@ -255,7 +254,7 @@ message Subscription { message FetchSubscriptionsRequest { oneof request { // Topic to register/unregister to receive subscription change notifications - v1.UUri topic = 1; + uprotocol.v1.UUri topic = 1; // Subscribers's information SubscriberInfo subscriber = 2; @@ -273,9 +272,6 @@ message FetchSubscriptionsResponse { // Set to true if the batch did not return all records optional bool has_more_records = 2; - - // Status of the query - uprotocol.v1.UStatus status = 3; } @@ -284,13 +280,15 @@ message FetchSubscriptionsResponse { // as information about the subscriber who wishes to receive said notifications message NotificationsRequest { // Topic to register/unregister to receive subscription change notifications - v1.UUri topic = 1; + uprotocol.v1.UUri topic = 1; // Subscribers's information SubscriberInfo subscriber = 2; } - +// The (empty) response message representing the successful execution of the +// RegisterForSubscriptionChanges and UnregisterForSubscriptionChanges operations. +message NotificationsResponse {} // Subscription Update Message. // This Update message is sent from uSusbcription on the topic: @@ -299,12 +297,12 @@ message NotificationsRequest { // any uE that called RegisterForNotifications(). message Update { // Subscribed topic whos state has changed - v1.UUri topic = 1; + uprotocol.v1.UUri topic = 1; // Information about the subscriber who changed their subscription SubscriberInfo subscriber = 2; - // Current status of the subscription (state, code, etc...) + // Current status of the subscription SubscriptionStatus status = 3; // Subscribers subscription attributes @@ -354,3 +352,6 @@ message ResetRequest { } } } + +// The (empty) response message representing the successful execution of the Reset operation. +message ResetResponse {} diff --git a/up-core-api/uprotocol/core/utwin/v2/utwin.proto b/up-core-api/uprotocol/core/utwin/v2/utwin.proto index c2871cc..69885dd 100644 --- a/up-core-api/uprotocol/core/utwin/v2/utwin.proto +++ b/up-core-api/uprotocol/core/utwin/v2/utwin.proto @@ -32,25 +32,23 @@ service uTwin { option (uprotocol.service_id) = 26; // A uE calls this API to retrieve the last uMessages for a given set of topics.
- // What is returned is a list of MessageResponse with the status for message retreival + // What is returned is a list of MessageResponse with the status for message retrieval // and the event itself if uTwin was able to fetch it. uTwin will also return // status for those messages that it was unable to fetch (i.e. due to NOT_FOUND // or PERMISSION_DENIED.
- rpc GetLastMessages(uprotocol.v1.UUriBatch) returns (GetLastMessagesResponse) { + rpc GetLastMessages(GetLastMessagesRequest) returns (GetLastMessagesResponse) { option (uprotocol.method_id) = 1; } // A call to SetLasMessage (typically from uBus) to update the uTwin internal cache // with a message for a given topic (UMessage.source). - // Return value status.Code is one of: - // - OK if UMessage was successfully stored in uTwin - // - INVALID argument if uTwin encountered an issue with UMessage content (source field in particular) + // If setting the value fails, the response is a UStatus with code + // - INVALID_ARGUMENT if uTwin encountered an issue with UMessage content (source field in particular) // - PERMISSION_DENIED if requesting uE does not have permission to access the Topic // - RESOURCE_EXHAUSTED if uTwin has no more memory available to store new UMessages - rpc SetLastMessage(uprotocol.v1.UMessage) returns (uprotocol.v1.UStatus) { + rpc SetLastMessage(SetLastMessageRequest) returns (SetLastMessageResponse) { option (uprotocol.method_id) = 2; } - } @@ -66,9 +64,22 @@ message MessageResponse { uprotocol.v1.UMessage message = 3; } +// The request message for the GetLastMessage operation. +message GetLastMessagesRequest { + // The topics to get the last message for + uprotocol.v1.UUriBatch topics = 1; +} // Message returned by the rpc GetLastMessages. message GetLastMessagesResponse { // List of one or more messages and the results for fetching the message per topic repeated MessageResponse responses = 2; } + +// The request message for the SetLastMessage operation. +message SetLastMessageRequest { + uprotocol.v1.UMessage message = 1; +} + +// The (empty) response message representing the successful execution of the SetLastMessage operation. +message SetLastMessageResponse {}