Diffusion C API  6.10.2
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
topics.h File Reference

Subscription to topics and fetching topic data. More...

Data Structures

struct  subscription_handlers_s
 
struct  subscription_params_s
 Structure supplied when subscribing to a topic. More...
 
struct  svc_notify_subscription_request_s
 Structure describing an incoming notification that the client has been subscribed to a topic. More...
 
struct  notify_subscription_handlers_s
 
struct  notify_subscription_params_s
 Structure supplied when registering to receive topic subscription notifications. More...
 
struct  unsubscription_handlers_s
 
struct  unsubscription_params_s
 Structure supplied when unsubscribing from a topic. More...
 
struct  svc_notify_unsubscription_request_s
 Structure describing an incoming unsubscription notification. More...
 
struct  notify_unsubscription_handlers_s
 
struct  notify_unsubscription_params_s
 Structure supplied when registering to receive topic unsubscription notifications. More...
 

Macros

#define SUBSCRIPTION_HANDLERS
 Callback handlers that may be registered to deal with messages sent by Diffusion in response to the subscription request.
 
#define NOTIFY_SUBSCRIPTION
 Callback handlers for subscription notification messages.
 
#define UNSUBSCRIPTION_HANDLERS
 Callback handlers that may be registered to deal with messages sent by Diffusion in response to the unsubscription request.
 
#define NOTIFY_UNSUBSCRIPTION
 Callback handlers for unsubscription notification callbacks.
 

Typedefs

typedef int(* on_subscribe_cb )(SESSION_T *session, void *context)
 Callback for on_subscribe(). More...
 
typedef struct
subscription_params_s 
SUBSCRIPTION_PARAMS_T
 Structure supplied when subscribing to a topic.
 
typedef struct
svc_notify_subscription_request_s 
SVC_NOTIFY_SUBSCRIPTION_REQUEST_T
 Structure describing an incoming notification that the client has been subscribed to a topic.
 
typedef int(* on_notify_subscription_cb )(SESSION_T *session, const SVC_NOTIFY_SUBSCRIPTION_REQUEST_T *request, void *context)
 Callback for notify_subscription_register(). More...
 
typedef struct
notify_subscription_params_s 
NOTIFY_SUBSCRIPTION_PARAMS_T
 Structure supplied when registering to receive topic subscription notifications.
 
typedef int(* on_unsubscribe_cb )(SESSION_T *session, void *context)
 Callback for on_unsubscribe(). More...
 
typedef struct
unsubscription_params_s 
UNSUBSCRIPTION_PARAMS_T
 Structure supplied when unsubscribing from a topic.
 
typedef struct
svc_notify_unsubscription_request_s 
SVC_NOTIFY_UNSUBSCRIPTION_REQUEST_T
 Structure describing an incoming unsubscription notification.
 
typedef int(* on_notify_unsubscription_cb )(SESSION_T *session, const SVC_NOTIFY_UNSUBSCRIPTION_REQUEST_T *request, void *context)
 Callback for notify_unsubscription_register. More...
 
typedef struct
notify_unsubscription_params_s 
NOTIFY_UNSUBSCRIPTION_PARAMS_T
 Structure supplied when registering to receive topic unsubscription notifications.
 

Enumerations

enum  NOTIFY_UNSUBSCRIPTION_REASON_T {
  UNSUBSCRIPTION_REASON_REQUESTED, UNSUBSCRIPTION_REASON_CONTROL, UNSUBSCRIPTION_REASON_REMOVAL, UNSUBSCRIPTION_REASON_AUTHORIZATION,
  UNSUBSCRIPTION_REASON_UNKNOWN_UNSUBSCRIBE_REASON, UNSUBSCRIPTION_REASON_BACK_PRESSURE, UNSUBSCRIPTION_REASON_BRANCH_MAPPINGS, UNSUBSCRIPTION_REASON_SUBSCRIPTION_REFRESH,
  UNSUBSCRIPTION_REASON_STREAM_CHANGE
}
 Reason for unsubscription. More...
 

Functions

TOPIC_HANDLER_T subscribe (SESSION_T *session, const SUBSCRIPTION_PARAMS_T params)
 Subscribe to topics. More...
 
void notify_subscription_register (SESSION_T *session, const NOTIFY_SUBSCRIPTION_PARAMS_T params)
 Register to receive subscription notifications. More...
 
void unsubscribe (SESSION_T *session, const UNSUBSCRIPTION_PARAMS_T params)
 Unsubscribe from one or more topics. More...
 
void notify_unsubscription_register (SESSION_T *session, const NOTIFY_UNSUBSCRIPTION_PARAMS_T params)
 Register to receive unsubscription notifications. More...
 
DIFFUSION_FETCH_REQUEST_Tdiffusion_fetch_request_init (SESSION_T *session)
 Creates an unconfigured fetch request. More...
 
DIFFUSION_FETCH_REQUEST_Tdiffusion_fetch_request_dup (const DIFFUSION_FETCH_REQUEST_T *fetch_request)
 Create a duplicate (copy) of an existing DIFFUSION_FETCH_REQUEST_T. More...
 
void diffusion_fetch_request_free (DIFFUSION_FETCH_REQUEST_T *fetch_request)
 Free a memory allocated DIFFUSION_FETCH_REQUEST_T More...
 

Detailed Description

Subscription to topics and fetching topic data.

Typedef Documentation

typedef int(* on_notify_subscription_cb)(SESSION_T *session, const SVC_NOTIFY_SUBSCRIPTION_REQUEST_T *request, void *context)

Callback for notify_subscription_register().

Parameters
sessionThe current active session.
requestThe incoming notification request.
contextUser-supplied context from the initial registration call.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* on_notify_unsubscription_cb)(SESSION_T *session, const SVC_NOTIFY_UNSUBSCRIPTION_REQUEST_T *request, void *context)

Callback for notify_unsubscription_register.

Parameters
sessionThe current active session.
requestThe incoming notification message.
contextUser-supplied context from the initial registration call.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* on_subscribe_cb)(SESSION_T *session, void *context)

Callback for on_subscribe().

Parameters
sessionThe current active session.
contextUser-supplied context from the initial subscribe() call.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.
typedef int(* on_unsubscribe_cb)(SESSION_T *session, void *context)

Callback for on_unsubscribe().

Parameters
sessionThe current active session.
contextUser-supplied context from the initial unsubscribe() call.
Returns
HANDLER_SUCCESS or HANDLER_FAILURE.

Enumeration Type Documentation

Reason for unsubscription.

Enumerator
UNSUBSCRIPTION_REASON_REQUESTED 

Unsubscribed by the subscribing client.

Since
5.6
UNSUBSCRIPTION_REASON_CONTROL 

The unsubscription was requested either by another client or by the server.

Since
5.6
UNSUBSCRIPTION_REASON_REMOVAL 

The unsubscription occurred because the topic was removed.

Since
5.6
UNSUBSCRIPTION_REASON_AUTHORIZATION 

The unsubscription occurred because the session is no longer authorized to access the topic.

Since
5.9
UNSUBSCRIPTION_REASON_UNKNOWN_UNSUBSCRIBE_REASON 

A reason that is unsupported by the session.

Since
6.1
UNSUBSCRIPTION_REASON_BACK_PRESSURE 

The server has a significant backlog of messages for the session, and the topic specification has the DIFFUSION_CONFLATION topic property set to "unsubscribe".

The session can resubscribe to the topic. The unsubscription is not persisted to the cluster, if the session fails over to a different server it will be resubscribed to the topic.

Since
6.1
UNSUBSCRIPTION_REASON_BRANCH_MAPPINGS 

The unsubscription occurred because branch mapping rules changed.

Since
6.7
UNSUBSCRIPTION_REASON_SUBSCRIPTION_REFRESH 

The server has re-subscribed this session to the topic.

Existing streams are unsubscribed because the topic type and other attributes may have changed.

This can happen if a set of servers is configured to use session replication, and a session connected to one server reconnects ("fails over") to a different server.

A stream that receives an unsubscription notification with this reason will also receive a subscription notification with the new topic specification.

Since
5.9
UNSUBSCRIPTION_REASON_STREAM_CHANGE 

A fallback stream has been unsubscribed due to the addition of a stream that selects the topic.

Since
5.9