DEPRECATED: Diffusion C Classic API  5.9.4
 All Data Structures Files Functions Pages
diffusion.h File Reference

Diffusion C API declarations. More...

Go to the source code of this file.

Data Structures

struct  SECURITY_CREDENTIALS
 
struct  DIFFUSION_CONNECTION_RESPONSE
 
struct  DIFFUSION_PAGE_NOTIFICATION
 
struct  DIFFUSION_SERVER_DETAILS
 
struct  DIFFUSION_CONNECTION
 
struct  DIFFUSION_MESSAGE
 
struct  DIFFUSION_CALLBACKS
 

Macros

#define DIFFUSION_SUCCESS   0
 
#define DIFFUSION_ERROR   -1
 
#define DIFFUSION_INVALID_PROTOCOL_VERSION   -2
 
#define DIFFUSION_MD   0x00
 
#define DIFFUSION_RD   0x01
 
#define DIFFUSION_FD   0x02
 
#define DIFFUSION_MSG_TOPIC_LOAD   0x14
 
#define DIFFUSION_MSG_DELTA   0x15
 
#define DIFFUSION_MSG_SUBSCRIBE   0x16
 
#define DIFFUSION_MSG_UNSUBSCRIBE   0x17
 
#define DIFFUSION_MSG_PING_SERVER   0x18
 
#define DIFFUSION_MSG_PING_CLIENT   0x19
 
#define DIFFUSION_MSG_CREDENTIALS   0x1A
 
#define DIFFUSION_MSG_CREDENTIALS_REJECTED   0x1B
 
#define DIFFUSION_ABORT_NOTIFICATION   0x1C
 
#define DIFFUSION_CLOSE_REQUEST   0x1D
 
#define DIFFUSION_MSG_TOPIC_LOAD_ACK   0x1E
 
#define DIFFUSION_MSG_DELTA_ACK   0x1F
 
#define DIFFUSION_MSG_ACK   0x20
 
#define DIFFUSION_MSG_FETCH   0x21
 
#define DIFFUSION_MSG_FETCH_REPLY   0x22
 
#define DIFFUSION_MSG_TOPIC_STATUS_NOTIFICATION   0x23
 
#define DIFFUSION_MSG_COMMAND   0x24
 
#define DIFFUSION_MSG_COMMAND_TOPIC_LOAD   0x28
 
#define DIFFUSION_MSG_COMMAND_TOPIC_NOTIFICATION   0x29
 
#define DIFFUSION_FLAG_RECONNECT   0x01
 
#define DIFFUSION_FLAG_LOAD_BALANCE   0x02
 
#define DIFFUSION_COMMAND_ID_SERVICE_TOPIC   "0"
 
#define DIFFUSION_COMMAND_ID_PAGED_TOPIC   "1"
 
#define DIFFUSION_PAGINATED_DATA_TYPE_STRING   "PS"
 
#define DIFFUSION_PAGINATED_DATA_TYPE_RECORD   "PR"
 
#define DIFFUSION_DEBUG(...)   if(_diffusion_debug) { printf(__VA_ARGS__); }
 
#define DIFF_CB_ZERO(cb)   memset(&cb, 0, sizeof(cb))
 

Functions

DIFFUSION_CONNECTIONdiff_connect (const char *hostname, const int port, const SECURITY_CREDENTIALS *credentials)
 Connect to a Diffusion server. More...
 
DIFFUSION_CONNECTIONdiff_connect_server (DIFFUSION_SERVER_DETAILS *details)
 Connect to a Diffusion server as an External Client. More...
 
DIFFUSION_CONNECTIONdiff_reconnect_server (DIFFUSION_SERVER_DETAILS *details, const char *client_id)
 If a client_id is supplied, attempt to reconnect to a Diffusion server, restoring state and allowing any queued messages to be received. More...
 
DIFFUSION_CONNECTIONdiff_connect_cascade (LLIST *server_list, int flags, const char *client_id)
 Iterate through a list of DIFFUSION_CONNECTION pointers until a connection is successfully made. More...
 
int diff_connect_request (DIFFUSION_CONNECTION *connection)
 Send a connection request message to the Diffusion server, connecting as a C client. More...
 
int diff_disconnect (DIFFUSION_CONNECTION *connection)
 Send a disconnection request to the Diffusion server and close the connection. More...
 
int diff_reconnect (DIFFUSION_CONNECTION *connection)
 Attempt to reconnect to a server which has been previously connected. More...
 
void diff_free_connection (DIFFUSION_CONNECTION *connection)
 Frees the memory associated with a Diffusion connection structure. More...
 
int diff_subscribe (DIFFUSION_CONNECTION *connection, const char *topic_set)
 Send a subscription request to a connected Diffusion server. More...
 
int diff_unsubscribe (DIFFUSION_CONNECTION *connection, const char *topic_set)
 Send a request to unsubscribe from one or more topics. More...
 
int diff_ping (DIFFUSION_CONNECTION *connection)
 Send a server ping request to a Diffusion server. More...
 
int diff_ping_response (DIFFUSION_CONNECTION *connection, DIFFUSION_MESSAGE *message)
 Send a client ping back to Diffusion in response to a client ping. More...
 
int diff_ack_response (DIFFUSION_CONNECTION *connection, DIFFUSION_MESSAGE *message)
 Send an ACK response to a message. More...
 
int diff_send_message (DIFFUSION_CONNECTION *connection, DIFFUSION_MESSAGE *message)
 Send a message to Diffusion. More...
 
int diff_send_data (DIFFUSION_CONNECTION *connection, const char *topic, const char *data)
 Convenience function for sending NULL-terminated data to Diffusion. More...
 
int diff_send_data_length (DIFFUSION_CONNECTION *connection, const char *topic, const char *data, const long length)
 Convenience function for sending arbitrary length data to Diffusion. More...
 
int diff_fetch (DIFFUSION_CONNECTION *connection, const char *topic_set)
 Fetch data from one or more topics. More...
 
int diff_fetch_correlated (DIFFUSION_CONNECTION *connection, const char *topic_set, LLIST *header_list)
 Fetch data from Diffusion, with headers that are reflected back in the Initial Topic Load response(s). More...
 
int diff_send_credentials (DIFFUSION_CONNECTION *connection, SECURITY_CREDENTIALS *credentials)
 Send new credentials to Diffusion, or replace existing credentials. More...
 
int diff_send_command (DIFFUSION_CONNECTION *connection, DIFFUSION_MESSAGE *message, const char *command, const char *correlation_id)
 Send a command topic message. More...
 
int diff_page_open (DIFFUSION_CONNECTION *connection, const char *topic, const int page_size, const int start_page)
 Send a "page open" command message. More...
 
int diff_page_refresh (DIFFUSION_CONNECTION *connection, const char *topic)
 Send a "page refresh" command message. More...
 
int diff_page_next (DIFFUSION_CONNECTION *connection, const char *topic)
 Send a "page next" command message. More...
 
int diff_page_prior (DIFFUSION_CONNECTION *connection, const char *topic)
 Send a "page prior" command message. More...
 
int diff_page_first (DIFFUSION_CONNECTION *connection, const char *topic)
 Send a "page first" command message. More...
 
int diff_page_last (DIFFUSION_CONNECTION *connection, const char *topic)
 Send a "page last" command message. More...
 
int diff_page_number (DIFFUSION_CONNECTION *connection, const char *topic, const int page_number)
 Send a "page number" command message. More...
 
int diff_page_close (DIFFUSION_CONNECTION *connection, const char *topic)
 Send a "page close" command message. More...
 
DIFFUSION_MESSAGEdiff_wait_for_message (DIFFUSION_CONNECTION *connection, long timeout)
 Wait for a message from the Diffusion server and return it. More...
 
DIFFUSION_MESSAGEdiff_read_message (DIFFUSION_CONNECTION *connection)
 Read a message from Diffusion connection. More...
 
DIFFUSION_MESSAGEdiff_decode_message (const int len, const char *buf, DIFFUSION_CONNECTION *connection)
 Parses a raw message read from a socket into a DIFFUSION_MESSAGE structure. More...
 
DIFFUSION_MESSAGEdiff_create_message (const LLIST *header_list, const char *data)
 Create a new DIFFUSION_MESSAGE with headers and data. More...
 
DIFFUSION_MESSAGEdiff_create_message_length (const LLIST *header_list, const char *data, const long length)
 Create a new DIFFUSION_MESSAGE with headers and data. More...
 
DIFFUSION_MESSAGEdiff_dup_message (const DIFFUSION_MESSAGE *msg)
 Copy an existing DIFFUSION_MESSAGE. More...
 
void diff_free_message (DIFFUSION_MESSAGE *msg)
 Free all memory associated with a DIFFUSION_MESSAGE. More...
 
DIFFUSION_PAGE_NOTIFICATIONdiff_create_page_notification (DIFFUSION_MESSAGE *msg)
 Create and populate a DIFFUSION_PAGE_NOTIFICATION structure from a DIFFUSION_MESSAGE which contains appropriate information. More...
 
void diff_free_page_notification (DIFFUSION_PAGE_NOTIFICATION *notification)
 Free memory associated with a DIFFUSION_PAGE_NOTIFICATION strucure. More...
 
void diff_msg_add_header (DIFFUSION_MESSAGE *msg, const char *data)
 Add a new header to an existing message. More...
 
void diff_msg_request_ack (DIFFUSION_MESSAGE *msg)
 Set the "ACK requested" flag on a DIFFUSION_MESSAGE. More...
 
void diff_debug_message (DIFFUSION_MESSAGE *msg)
 Utility function for displaying a DIFFUSION_MESSAGE to the console. More...
 
void diff_loop (DIFFUSION_CONNECTION *connection, DIFFUSION_CALLBACKS *callbacks)
 Calling this function will initiate a processing loop, where messages from Diffusion are read and the appropriate callbacks are invoked. More...
 
void diff_main (DIFFUSION_CONNECTION *connection, LLIST *server_list, DIFFUSION_CALLBACKS *callbacks, int flags)
 This function will begin a loop, receiving messages from Diffusion and invoking the appropriate callback function to handle them. More...
 
void diff_dispatch (DIFFUSION_MESSAGE *msg, DIFFUSION_CALLBACKS *callbacks, DIFFUSION_CONNECTION *connection)
 Call the relevant callback function for the given message. More...
 
char * diff_add_topic_listener (DIFFUSION_CONNECTION *connection, const char *topic_pattern, int(*listener)(DIFFUSION_MESSAGE *))
 Add a listener function for a topic or regular expression The listener should return 1 if the message has been consumed, or 0 if it should be allowed to pass to any other listeners which have registered an interest in the topic. More...
 
void diff_remove_topic_listener (DIFFUSION_CONNECTION *connection, const char *ref)
 Remove a registered topic listener. More...
 
char * diff_add_service_listener (DIFFUSION_CONNECTION *connection, const char *topic_pattern, int(*listener)(DIFFUSION_MESSAGE *))
 Add a service topic listener. More...
 
void diff_remove_service_listener (DIFFUSION_CONNECTION *connection, const char *ref)
 Remove a registered service listener. More...
 

Variables

int _diffusion_debug
 

Detailed Description

Diffusion C API declarations.

Copyright © 2014, 2015 Push Technology Ltd., All Rights Reserved.

Use is subject to license terms.

NOTICE: All information contained herein is, and remains the property of Push Technology. The intellectual and technical concepts contained herein are proprietary to Push Technology and may be covered by U.S. and Foreign Patents, patents in process, and are protected by trade secret or copyright law.

Definition in file diffusion.h.

Function Documentation

int diff_ack_response ( DIFFUSION_CONNECTION connection,
DIFFUSION_MESSAGE message 
)

Send an ACK response to a message.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
messageThe message to be ACKed.
Return values
int0 on success, -1 on error.
char* diff_add_service_listener ( DIFFUSION_CONNECTION connection,
const char *  topic_pattern,
int(*)(DIFFUSION_MESSAGE *)  listener 
)

Add a service topic listener.

This is called in place of a standard topic listener if the message is one of the service type messages (including paged topic data). Returning non-zero indicates that the message has been handled and no other listeners for this topic should be called.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
topic_patternA pointer to a regular expression to match against a topic name.
listenerA function to call which will process a DIFFUSION_MESSAGE, if the regular expression matches.
Return values
intA pointer to a reference for identifying this listener, or NULL if an error occurs.
char* diff_add_topic_listener ( DIFFUSION_CONNECTION connection,
const char *  topic_pattern,
int(*)(DIFFUSION_MESSAGE *)  listener 
)

Add a listener function for a topic or regular expression The listener should return 1 if the message has been consumed, or 0 if it should be allowed to pass to any other listeners which have registered an interest in the topic.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
topic_patternA pointer to a regular expression to match against a topic name.
listenerA function to call which will process a DIFFUSION_MESSAGE, if the regular expression matches.
Return values
intA pointer to a reference for identifying this listener, or NULL if an error occurs.
DIFFUSION_CONNECTION* diff_connect ( const char *  hostname,
const int  port,
const SECURITY_CREDENTIALS credentials 
)

Connect to a Diffusion server.

Returns NULL on failure. A valid DIFFUSION_CONNECTION structure should be freed by the caller after use by means of the diff_free_connection() function.

Deprecated:
This function is deprecated in favour of diff_connect_server()
Parameters
hostnameHostname or IP address of Diffusion host to connect to.
portDestination port of Diffusion server.
credentialsPointer to a complete SECURITY_CREDENTIALS structure, or NULL if no credentials necessary.
Return values
DIFFUSION_CONNECTION *Returns a pointer to a DIFFUSION_CONNECTION or NULL on error.
DIFFUSION_CONNECTION* diff_connect_cascade ( LLIST server_list,
int  flags,
const char *  client_id 
)

Iterate through a list of DIFFUSION_CONNECTION pointers until a connection is successfully made.

If supplied, the client_id is used in order to attempt to restore state, receiving queued messages from Diffusion (if configured for this).

If the flags parameter is set to 0, the list is iterated in order.
If set to DIFFUSION_FLAG_LOAD_BALANCE, the list is randomly shuffled.

Parameters
server_listA pointer to a linked list (LLIST) of pointers to populated DIFFUSION_SERVER_DETAILS structures.
flagsFlags controlling how the list is iterated.
client_idThe client_id of the previous successful connection, or NULL if not known.
Return values
DIFFUSION_CONNECTION *A pointer to a DIFFUSION_CONNECTION or NULL.
int diff_connect_request ( DIFFUSION_CONNECTION connection)

Send a connection request message to the Diffusion server, connecting as a C client.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
Return values
int0 on success, -1 on error.
DIFFUSION_CONNECTION* diff_connect_server ( DIFFUSION_SERVER_DETAILS details)

Connect to a Diffusion server as an External Client.

Parameters
detailsA pointer to a populated DIFFUSION_SERVER_DETAILS structure.
Return values
DIFFUSION_CONNECTION *Pointer to a DIFFUSION_CONNECTION or NULL on error.
DIFFUSION_MESSAGE* diff_create_message ( const LLIST header_list,
const char *  data 
)

Create a new DIFFUSION_MESSAGE with headers and data.

When the message is no longer required, the memory it uses should be deallocated with diff_free_message().

Parameters
header_listA list of headers to assign to the message.
dataThe message body.
Return values
DIFFUSION_MESSAGE *A pointer to a DIFFUSION_MESSAGE, or NULL on error.
DIFFUSION_MESSAGE* diff_create_message_length ( const LLIST header_list,
const char *  data,
const long  length 
)

Create a new DIFFUSION_MESSAGE with headers and data.

When the message is no longer required, the memory it uses should be deallocated with diff_free_message().

Parameters
header_listA list of headers to assign to the message.
dataThe NULL-terminated message body.
lengthThe length of the message body.
Return values
DIFFUSION_MESSAGE *A pointer to a DIFFUSION_MESSAGE, or NULL on error.
DIFFUSION_PAGE_NOTIFICATION* diff_create_page_notification ( DIFFUSION_MESSAGE msg)

Create and populate a DIFFUSION_PAGE_NOTIFICATION structure from a DIFFUSION_MESSAGE which contains appropriate information.

Parameters
msgAn existing DIFFUSION_MESSAGE
Return values
DIFFUSION_PAGE_NOTIFICATION *A pointer to a new DIFFUSION_PAGE_NOTIFICATION, or NULL on error.
void diff_debug_message ( DIFFUSION_MESSAGE msg)

Utility function for displaying a DIFFUSION_MESSAGE to the console.

Parameters
msgA pointer to a DIFFUSION_MESSAGE.
DIFFUSION_MESSAGE* diff_decode_message ( const int  len,
const char *  buf,
DIFFUSION_CONNECTION connection 
)

Parses a raw message read from a socket into a DIFFUSION_MESSAGE structure.

Given a byte array and length, attempt to parse into a DIFFUSION_MESSAGE structure. The memory for the message is allocated internally and should be freed with diff_free_message() once it is no longer required.

If an unparsable byte array is received, NULL is returned.

Parameters
lenNumber of bytes in buffer
bufBuffer containing the raw message.
connectionA pointer to the DIFFUSION_CONNECTION structure which was used when reading the data.
Return values
DIFFUSION_MESSAGE *A pointer to a DIFFUSION_MESSAGE, or NULL if the message could not be decoded.
int diff_disconnect ( DIFFUSION_CONNECTION connection)

Send a disconnection request to the Diffusion server and close the connection.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
Return values
int0 on success, -1 on error
void diff_dispatch ( DIFFUSION_MESSAGE msg,
DIFFUSION_CALLBACKS callbacks,
DIFFUSION_CONNECTION connection 
)

Call the relevant callback function for the given message.

Parameters
msgA pointer to a DIFFUSION_MESSAGE structure.
callbacksA pointer to a DIFFUSION_CALLBACKS structure.
connectionA pointer to the DIFFUSION_CONNECTION structure from which the message originated.
DIFFUSION_MESSAGE* diff_dup_message ( const DIFFUSION_MESSAGE msg)

Copy an existing DIFFUSION_MESSAGE.

Parameters
msgAn existing DIFFUSION_MESSAGE
Return values
DIFFUSION_MESSAGE *A pointer to a copy of the input DIFFUSION_MESSAGE or NULL.
int diff_fetch ( DIFFUSION_CONNECTION connection,
const char *  topic_set 
)

Fetch data from one or more topics.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
topic_setA comma-separated list of topics to fetch.
Return values
int0 on success, -1 on error.
int diff_fetch_correlated ( DIFFUSION_CONNECTION connection,
const char *  topic_set,
LLIST header_list 
)

Fetch data from Diffusion, with headers that are reflected back in the Initial Topic Load response(s).

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
topic_setA comma-separated list of topics to fetch.
header_listA list of header values that are expected in the response(s).
Return values
int0 on success, -1 on error.
void diff_free_connection ( DIFFUSION_CONNECTION connection)

Frees the memory associated with a Diffusion connection structure.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
void diff_free_message ( DIFFUSION_MESSAGE msg)

Free all memory associated with a DIFFUSION_MESSAGE.

Parameters
msgA pointer to a DIFFUSION_MESSAGE structure.
void diff_free_page_notification ( DIFFUSION_PAGE_NOTIFICATION notification)

Free memory associated with a DIFFUSION_PAGE_NOTIFICATION strucure.

Parameters
notificationA pointer to a DIFFUSION_PAGE_NOTIFICATION_MESSAGE.
void diff_loop ( DIFFUSION_CONNECTION connection,
DIFFUSION_CALLBACKS callbacks 
)

Calling this function will initiate a processing loop, where messages from Diffusion are read and the appropriate callbacks are invoked.

This function will exit if the connection to Diffusion is lost.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
callbacksA pointer to a DIFFUSION_CALLBACKS structure.
void diff_main ( DIFFUSION_CONNECTION connection,
LLIST server_list,
DIFFUSION_CALLBACKS callbacks,
int  flags 
)

This function will begin a loop, receiving messages from Diffusion and invoking the appropriate callback function to handle them.

The loop is only exited when a connection to any of the supplied Diffusion server cannot be made.

If the connection is lost and the flags mask contains DIFFUSION_FLAG_RECONNECT, a reconenction attempt is made back to the same Diffusion server for a number of times as defined in the current connection.

If the flag is not set or the reconnection is unsuccessful, the next server in server_list is attempted. The order in which these servers are attempted is mandated by the presence of DIFFUSION_FLAG_LOAD_BALANCE. See diff_connect_cascade().

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure used for the initial communication with Diffusion, or NULL if a connection should be attempted with diff_connect_cascade().
server_listA list of pointers to DIFFUSION_SERVER_DETAILS structures.
callbacksA pointer to a DIFFUSION_CALLBACKS structure.
flagsA bitmask specifying the reconnect logic.
void diff_msg_add_header ( DIFFUSION_MESSAGE msg,
const char *  data 
)

Add a new header to an existing message.

Parameters
msgA pointer to a DIFFUSION_MESSAGE.
dataThe header data.
void diff_msg_request_ack ( DIFFUSION_MESSAGE msg)

Set the "ACK requested" flag on a DIFFUSION_MESSAGE.

Parameters
msgA pointer to a DIFFUSION_MESSAGE.
int diff_page_close ( DIFFUSION_CONNECTION connection,
const char *  topic 
)

Send a "page close" command message.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
topicThe topic name.
Return values
int0 on success, -1 on error.
int diff_page_first ( DIFFUSION_CONNECTION connection,
const char *  topic 
)

Send a "page first" command message.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
topicThe topic name.
Return values
int0 on success, -1 on error.
int diff_page_last ( DIFFUSION_CONNECTION connection,
const char *  topic 
)

Send a "page last" command message.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
topicThe topic name.
Return values
int0 on success, -1 on error.
int diff_page_next ( DIFFUSION_CONNECTION connection,
const char *  topic 
)

Send a "page next" command message.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
topicThe topic name.
Return values
int0 on success, -1 on error.
int diff_page_number ( DIFFUSION_CONNECTION connection,
const char *  topic,
const int  page_number 
)

Send a "page number" command message.

This causes the page pointer to jump directly to a new page.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
topicThe topic name.
page_numberThe requested page number.
Return values
int0 on success, -1 on error.
int diff_page_open ( DIFFUSION_CONNECTION connection,
const char *  topic,
const int  page_size,
const int  start_page 
)

Send a "page open" command message.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
topicThe topic name.
page_sizeThe size of the page to be opened.
start_pageThe page number to open.
Return values
int0 on success, -1 on error.
int diff_page_prior ( DIFFUSION_CONNECTION connection,
const char *  topic 
)

Send a "page prior" command message.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
topicThe topic name.
Return values
int0 on success, -1 on error.
int diff_page_refresh ( DIFFUSION_CONNECTION connection,
const char *  topic 
)

Send a "page refresh" command message.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
topicThe topic name.
Return values
int0 on success, -1 on error.
int diff_ping ( DIFFUSION_CONNECTION connection)

Send a server ping request to a Diffusion server.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
Return values
int0 on success, -1 on error.
int diff_ping_response ( DIFFUSION_CONNECTION connection,
DIFFUSION_MESSAGE message 
)

Send a client ping back to Diffusion in response to a client ping.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
messageThe client ping received for which a response is required.
Return values
int0 on success, -1 on error.
DIFFUSION_MESSAGE* diff_read_message ( DIFFUSION_CONNECTION connection)

Read a message from Diffusion connection.

This function will block until a message is available from the Diffusion server. The message is returned, and must be freed with diff_free_message() once it is no longer required.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
Return values
DIFFUSION_MESSAGE *A pointer to a DIFFUSION_MESSAGE, or NULL if a message could not be read.
int diff_reconnect ( DIFFUSION_CONNECTION connection)

Attempt to reconnect to a server which has been previously connected.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
Return values
int0 on success, -1 on error.
DIFFUSION_CONNECTION* diff_reconnect_server ( DIFFUSION_SERVER_DETAILS details,
const char *  client_id 
)

If a client_id is supplied, attempt to reconnect to a Diffusion server, restoring state and allowing any queued messages to be received.

If state could not be restored, or client_id is NULL then this function simply creates a new connection to the Diffusion server, or NULL on error.

Parameters
detailsA pointer to a populated DIFFUSION_SERVER_DETAILS structure.
client_idThe client_id of a previous connection or NULL.
Return values
DIFFUSION_CONNECTION *Pointer to a DIFFUSION_CONNECTION or NULL on error.
void diff_remove_service_listener ( DIFFUSION_CONNECTION connection,
const char *  ref 
)

Remove a registered service listener.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
refA pointer to a reference identifying the listener.
void diff_remove_topic_listener ( DIFFUSION_CONNECTION connection,
const char *  ref 
)

Remove a registered topic listener.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
refA pointer to a reference identifying the listener.
int diff_send_command ( DIFFUSION_CONNECTION connection,
DIFFUSION_MESSAGE message,
const char *  command,
const char *  correlation_id 
)

Send a command topic message.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
messageA pointer to a populated DIFFUSION_MESSAGE structure.
commandA command string which is interpreted by the command topic handler.
correlation_idAn ID which will be returned in the response.
Return values
int0 on success, -1 on error.
int diff_send_credentials ( DIFFUSION_CONNECTION connection,
SECURITY_CREDENTIALS credentials 
)

Send new credentials to Diffusion, or replace existing credentials.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
credentialsA pointer to a populated SECURITY_CREDENTIALS structure.
Return values
int0 on success, -1 on error.
int diff_send_data ( DIFFUSION_CONNECTION connection,
const char *  topic,
const char *  data 
)

Convenience function for sending NULL-terminated data to Diffusion.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
topicThe topic name to send data to.
dataNULL-terminated character data.
Return values
int0 on success, -1 on error.
int diff_send_data_length ( DIFFUSION_CONNECTION connection,
const char *  topic,
const char *  data,
const long  length 
)

Convenience function for sending arbitrary length data to Diffusion.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
topicThe topic name to send data to.
dataData to be sent.
lengthThe length of the data to send.
Return values
int0 on success, -1 on error.
int diff_send_message ( DIFFUSION_CONNECTION connection,
DIFFUSION_MESSAGE message 
)

Send a message to Diffusion.

The client must be subscribed to the topic. No warning is given if this is not the case.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
messageA pointer to a populated DIFFUSION_MESSAGE structure.
Return values
int0 on success, -1 on error.
int diff_subscribe ( DIFFUSION_CONNECTION connection,
const char *  topic_set 
)

Send a subscription request to a connected Diffusion server.

May be used to subscribe to an individual topic, or a set of topics. Multiple topics are specified by building a comma-separated list.

e.g.
diff_subscribe(cnx, "Echo");
diff_subscribe(cnx, "Echo,Trade");

No notification is given if any of the topics do not exist.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
topic_setA comma separated list of topic names.
Return values
int0 on success, -1 on error.
int diff_unsubscribe ( DIFFUSION_CONNECTION connection,
const char *  topic_set 
)

Send a request to unsubscribe from one or more topics.

topic_set is specified in the same way as a subscription, ie. a comma-separated list. No notification is given if any of the topics for which an unsubscription is requested do not exist, or are not currently subscribed to.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
topic_setA comma separated list of topic names.
Return values
int0 on success, -1 on error.
DIFFUSION_MESSAGE* diff_wait_for_message ( DIFFUSION_CONNECTION connection,
long  timeout 
)

Wait for a message from the Diffusion server and return it.

Waits for the Diffusion server to send a message to the client. The message returned as a pointer to a DIFFUSION_MESSAGE structure, which the user must free after use (see diff_free_message()).

If there is no message or a timeout occurs, NULL is returned. errno may be checked for the error code, if appropriate.

Parameters
connectionA pointer to a DIFFUSION_CONNECTION structure.
timeoutTime to wait for a message, in microseconds.
Return values
DIFFUSION_MESSAGE *A pointer to a DIFFUSION_MESSAGE, or NULL.