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

Topics feature. 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...
 
struct  svc_fetch_status_response_s
 Structure passed to fetch response callback. More...
 
struct  fetch_handlers_s
 
struct  fetch_params_s
 Structure supplied to a fetch() request. 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.
 
#define FETCH_HANDLERS
 Callbacks which can be registered for handling the responses to the fetch request.
 

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.
 
typedef struct
svc_fetch_status_response_s 
SVC_FETCH_STATUS_RESPONSE_T
 Structure passed to fetch response callback.
 
typedef int(* on_fetch_cb )(SESSION_T *session, void *context)
 Callback for on_fetch() command having been received by Diffusion. More...
 
typedef int(* on_fetch_status_message_cb )(SESSION_T *session, const SVC_FETCH_STATUS_RESPONSE_T *status, void *context)
 Callback for on_status_message() indicating the end of the fetch conversation. More...
 
typedef struct fetch_params_s FETCH_PARAMS_T
 Structure supplied to a fetch() request.
 

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_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...
 
 DEPRECATED (void fetch(SESSION_T *session, const FETCH_PARAMS_T params))
 Fetch state for a topic (or many topics). 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

Topics feature.

Typedef Documentation

typedef int(* on_fetch_cb)(SESSION_T *session, void *context)

Callback for on_fetch() command having been received by Diffusion.

Parameters
sessionThe currently active session.
contextUser-supplied context from the fetch() call.
Returns
HANDLERS_SUCCESS or HANDLER_FAILURE.
typedef int(* on_fetch_status_message_cb)(SESSION_T *session, const SVC_FETCH_STATUS_RESPONSE_T *status, void *context)

Callback for on_status_message() indicating the end of the fetch conversation.

Parameters
sessionThe currently active session.
statusThe fetch status response.
contextUser-supplied context from the fetch() call.
Returns
HANDLERS_SUCCESS or HANDLER_FAILURE.
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.

UNSUBSCRIPTION_REASON_CONTROL 

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

UNSUBSCRIPTION_REASON_REMOVAL 

The unsubscription occurred because the topic was removed.

UNSUBSCRIPTION_REASON_AUTHORIZATION 

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

UNSUBSCRIPTION_REASON_UNKNOWN_UNSUBSCRIBE_REASON 

A reason that is unsupported by the session.

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.

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 details.

UNSUBSCRIPTION_REASON_STREAM_CHANGE 

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

Function Documentation

DEPRECATED ( void   fetchSESSION_T *session, const FETCH_PARAMS_T params)

Fetch state for a topic (or many topics).

Deprecated:
This function is deprecated from version 6.2 onwards, and will be removed in a future release.
Parameters
sessionThe session handle. If NULL, the function returns immediately.
paramsParameters and callback handlers to be invoked to process the results of the fetch() call.