package uprotocol.core.usubscription.v3

Get desktop application:
View/edit binary Protocol Buffers messages

Subscription Service Interface definition

• rpc FetchSubscribers (FetchSubscribersRequest, FetchSubscribersResponse)

  usubscription.proto:81

  Fetch a list of subscribers that are currently subscribed to a given topic.

  message FetchSubscribersRequest

  usubscription.proto:217

  Passed to FetchSubscribers such that we can obtain a list of subscribers to a particular topic

  • optional v1.UUri topic = 1

    Topic we wish to find the subscribers for

  message FetchSubscribersResponse

  usubscription.proto:227

  Returned from FetchSubscribers(), this message contains a repeated list of SubscriberInfo

  • repeated SubscriberInfo subscribers = 1

    List of subscribers

• rpc FetchSubscriptions (FetchSubscriptionsRequest, FetchSubscriptionsResponse)

  usubscription.proto:64

  Fetch a list of subscriptions

  message FetchSubscriptionsRequest

  usubscription.proto:257

  • oneof request

    • v1.UUri topic = 1

      Topic to register/unregister to receive subscription change notifications

    • SubscriberInfo subscriber = 2

      Subscribers's information

  message FetchSubscriptionsResponse

  usubscription.proto:271

  Results from FetchSubscriptions() API

  • repeated Subscription subscriptions = 1

    Repeated list of subscriptions for a subscriber

• rpc RegisterForNotifications (NotificationsRequest, NotificationsResponse)

  usubscription.proto:71

  Register to receive subscription change notifications that are published on the 'up:/core.usubscription/3/subscriptions#Update'

• rpc Reset (ResetRequest, ResetResponse)

  usubscription.proto:92

  Reset subscriptions to and from the uSubscription Service. This API is used between uSubscription services in order to flush and reestablish subscriptions between devices. A uSubscription service might ned to call this API if its database is flushed or corrupted (ex. factory reset). **__NOTE:__** This is a private API only for uSubscription services, uEntities can call Unsubscribe() to flush their own subscriptions.

  message ResetRequest

  usubscription.proto:335

  Reset Subscriptions Request. Passed in the Reset() API this message contains the reason for the reset as well as the time before which all subscriptions should be reset.

  • optional ResetRequest.Reason reason = 1

    Reason for the reset

  message ResetResponse

  usubscription.proto:362

  The (empty) response message representing the successful execution of the Reset operation.

  (message has no fields)

• rpc Subscribe (SubscriptionRequest, SubscriptionResponse)

  usubscription.proto:53

  A consumer (application) calls this API to subscribe to a topic. What is passed is the SubscriptionRequest message containing the topic, the subscriber's name, and any Subscription Attributes. This API returns a SubscriptionResponse message containing the status of the request along with any event delivery configuration required to consume the event. Calling this API also registers the subscriber to received subscription change notifications if ever the subscription state changes.

  message SubscriptionRequest

  usubscription.proto:174

  Passed to Subscribe() contains the subscription request information

  • optional v1.UUri topic = 1

    uProtocol uri topic to subscribe too

  • optional SubscribeAttributes attributes = 3

    Additional subscription attributes

  message SubscriptionResponse

  usubscription.proto:188

  Response message from the Subscribe() API

  • optional SubscriptionStatus status = 1

    Current status of the subscription

  • optional EventDeliveryConfig config = 2

    Any platform (uDevice) specific additional event delivered configuration information for how the subscriber should consume the published events.

  • optional v1.UUri topic = 3

    Subscription topic passed to SubscriptionRequest

• rpc UnregisterForNotifications (NotificationsRequest, NotificationsResponse)

  usubscription.proto:76

  Unregister for subscription change events

• rpc Unsubscribe (UnsubscribeRequest, UnsubscribeResponse)

  usubscription.proto:59

  The consumer no longer wishes to subscribe to a topic so it issues an explicit unsubscribe request.

  message UnsubscribeRequest

  usubscription.proto:203

  Passed to the Unsubscribe() API, the message contains the topic to unsubscribe to as well as the subscriber identification

  • optional v1.UUri topic = 1

    Topic to be unsubscribed to

  message UnsubscribeResponse

  usubscription.proto:213

  The (empty) response message representing the successful execution of the Unsubscribe operation.

  (message has no fields)

How events will be delivered to the subscriber. Usage of this structure is device-dependent

Used in: Subscription, SubscriptionResponse

• string id = 1

  Identifier for the event delivery endpoint, ex. topic name for events to be published to example for Azure uCloud: "SUBSCRIPTION_TOPIC"

• string type = 2

  What type of endpoint shall be used to deliver the events for said subscription example for Azure uCloud: "Microsoft.EventHub/Namespaces/EventHubs"

• map<string, google.protobuf.Any> attributes = 3

  Any additional configuration attributes

Passed to the RegisterForSubscriptionChanges() and UnregisterForSubscriptionChanges() APIs this message includes the topic to register for subscription changes as well as information about the subscriber who wishes to receive said notifications

Used as request type in: uSubscription.RegisterForNotifications, uSubscription.UnregisterForNotifications

• optional v1.UUri topic = 1

  Topic to register/unregister to receive subscription change notifications

The (empty) response message representing the successful execution of the RegisterForSubscriptionChanges and UnregisterForSubscriptionChanges operations.

Used as response type in: uSubscription.RegisterForNotifications, uSubscription.UnregisterForNotifications

(message has no fields)

Passive Subscription Mode. Passive subscriptions, in lieu of active ones, do not modify (the state) nor notify the publisher of the subscribers subscription. Passive subscriptions are a means to support observability frameworks to passively listen for events. *NOTE*: This attribute is an internal platform setting (for now) and not exposed as part of SubscribeAttributes.

• bool enable = 1

  Enable passive subscription mode

The reason for triggering a reset, this is an optional attribute used to provide insight as to why a reset occurred More reasons will be added as we distill the business logic

Used in: ResetRequest

• Reason.Code code = 1

  Reason code

• optional string message = 2

  Reason message

Reason code

Used in: Reason

• UNSPECIFIED = 0

  Default non-specified reason for issuing a reset

• FACTORY_RESET = 1

  Factory reset

• CORRUPTED_DATA = 2

  Corrupted data

Additional subscription configurations information

Used in: Subscription, SubscriptionRequest, Update

• optional google.protobuf.Timestamp expire = 1

  When the subscription should expire (time in the future. **__NOTE:__** If this field is missing, assumed to live forever

• repeated google.protobuf.Any details = 2

  Any additional producer specific information that the consumer must send inside of a subscription request

• optional uint32 sample_period_ms = 3

  Desired Sampling Period (measured in milliseconds) the subscriber wishes to receive events for remote only topics. Device dispatchers (i.e. streamers) use this attribute to reduce the publication rates of events sent between devices. This attribute is commonly used for mobile/cloud subscribing to vehicle topics that are published at a high rate.<br> If the desired sampling period set by the subscriber is lower than the original publisher's publication period, the attribute is ignored.<br> **__NOTE:__** If this attribute is missing, the sampling period is set by the publisher.

Subscriber Identification Information

Used in: FetchSubscribersResponse, FetchSubscriptionsRequest, Subscription, Update

• optional v1.UUri uri = 1

  subscriber URI containig the names and numbers of the uEntities subscribing. Example represented in long form: `//device.domain/com.gm.app.hartley`

Subscription Message. Contains all the information about a subscription that is returned from FetchSubscriptions() API.

Used in: FetchSubscriptionsResponse

• optional v1.UUri topic = 1

  Subscription topic

• optional SubscriberInfo subscriber = 2

  Information about the subscriber who changed their subscription

• optional SubscriptionStatus status = 3

  Current status of the subscription

• optional SubscribeAttributes attributes = 4

  Subscribers subscription attributes

• optional EventDeliveryConfig config = 5

  Any platform (uDevice) specific additional event delivered configuration information for how the subscriber should consume the published events.

Subscription Status

Used in: Subscription, SubscriptionResponse, Update

• SubscriptionStatus.State state = 1

  Subscription state

• string message = 3

  The Subscription status message

Used in: SubscriptionStatus

• UNSUBSCRIBED = 0

  Default state to indicate not subscribed

• SUBSCRIBE_PENDING = 1

  Subscription is pending confirmation from remote

• SUBSCRIBED = 2

  Subscription has been successful

• UNSUBSCRIBE_PENDING = 3

  Unsubscribe is pending confirmation from the

Subscription Update Message. This Update message is sent from uSusbcription on the topic: '/core.usubscription/3/subscriptions#Update' whenever there is a change to a subscription. Subscribers automatically receive this notification along with any uEntities that called RegisterForNotifications().

• optional v1.UUri topic = 1

  Subscribed topic whos state has changed

• optional SubscriberInfo subscriber = 2

  Information about the subscriber who changed their subscription

• optional SubscriptionStatus status = 3

  Current status of the subscription

• optional SubscribeAttributes attributes = 4

  Subscribers subscription attributes

Service meta-data option definitions - Resources

• subscriptions = 0