Create a base context without libev (the hard way)

Data Structures
struct	wc_pollargs
struct	wc_timerargs
struct	wc_context_options

Macros
#define	WC_POLLHUP   (POLLHUP|POLLERR)
#define	WC_POLLIN   (POLLIN)
#define	WC_POLLOUT   (POLLOUT)
#define	WC_BASE_EVENT_OFFSET   0x00000001
#define	WC_DATASYNC_EVENT_OFFSET   0x00000100
#define	WC_AUTH_EVENT_OFFSET   0x00010000

Typedefs
typedef int(*	wc_on_event_cb_t) (wc_event_t event, wc_context_t *ctx, void *data, size_t len)

Enumerations
enum	wc_pollsrc { WC_POLL_DATASYNC, WC_POLL_AUTH, _WC_POLL_MAX }
enum	wc_timersrc { WC_TIMER_DATASYNC_KEEPALIVE, WC_TIMER_DATASYNC_RECONNECT, WC_TIMER_AUTH, _WC_TIMER_MAX }
enum	wc_event_t {   WC_EVENT_ADD_FD = WC_BASE_EVENT_OFFSET, WC_EVENT_DEL_FD, WC_EVENT_MODIFY_FD, WC_EVENT_SET_TIMER,   WC_EVENT_DEL_TIMER, WC_EVENT_ON_CNX_CLOSED = WC_DATASYNC_EVENT_OFFSET, WC_EVENT_ON_SERVER_HANDSHAKE, WC_EVENT_ON_MSG_RECEIVED,   WC_EVENT_ON_CNX_ERROR, WC_AUTH_ON_AUTH_REPLY = WC_AUTH_EVENT_OFFSET }

Functions
void	wc_dispatch_fd_event (wc_context_t *ctx, struct wc_pollargs *pa)
void	wc_dispatch_timer_event (wc_context_t *ctx, enum wc_timersrc timer)
void *	wc_context_get_user_data (wc_context_t *ctx)
wc_context_t *	wc_context_create (struct wc_context_options *options)
void	wc_context_destroy (wc_context_t *ctx)

Detailed Description

This SDK is fundamentally asynchronous, and is meant to be easily used in a mono-threaded application. The logic to achieve this is quite complex, and if you don't mind to depend on libev, there is no need to manually deal with any of the operations and concepts described below, go directly to the "connect with libev" section.

If you don't plan to rely on libev, here are the steps and logic to implement :

Populate a wc_context_options structure :

The wc_context_options::callback field must contain a pointer to a function you have defined (of type wc_on_event_cb_t) in your code, and that will be triggered by the SDK when various events happen (see wc_event_t).

Keep track of the requested file descriptors and timers

Whenever the SDK needs a file descriptor to be monitored for certain events, or a timer to be set, it will trigger the callback with the appropriate event and informations. For example, if the datasync part of the SDK needs the file descriptor 42 to be monitored for read and write availability, the callback will be called with the WC_EVENT_ADD_FD event, and the data parameter will point to a wc_pollargs structure containing the following informations:

{
    .fd = 42,
    .events = WC_POLLIN | WC_POLLOUT,
    .src = WC_POLL_DATASYNC,
}

To properly keep track of these events, an event-loop based on a poll-like mechanism needs to be implemented. This can be achieved by manually using poll, epoll, kqueue, ...

Inform the SDK whenever an event (I/O, timer) occurs

When a timer expires or a requested operation is available on a file descriptor, the appropriate methods must be called right away:

• wc_dispatch_timer_event() if a timer expired
• wc_dispatch_fd_event() if an I/O event occurred

Macro Definition Documentation

WC_AUTH_EVENT_OFFSET

#define WC_AUTH_EVENT_OFFSET   0x00010000

WC_BASE_EVENT_OFFSET

#define WC_BASE_EVENT_OFFSET   0x00000001

WC_DATASYNC_EVENT_OFFSET

#define WC_DATASYNC_EVENT_OFFSET   0x00000100

WC_POLLHUP

#define WC_POLLHUP   (POLLHUP|POLLERR)

WC_POLLIN

#define WC_POLLIN   (POLLIN)

WC_POLLOUT

#define WC_POLLOUT   (POLLOUT)

Typedef Documentation

wc_on_event_cb_t

typedef int(* wc_on_event_cb_t) (wc_event_t event, wc_context_t *ctx, void *data, size_t len)

This defines the callback type that must be passed to wc_cnx_new(). It will be called for the events listed in the wc_event_t enum. When triggered, the callback will receive these parameters:

Parameters

event	(mandatory) the event type that was triggered
ctx	(mandatory) the context on which the event occurred
data	(optional) some additional data about the event
len	(optional) the size of the additional data

Returns

a value to return to the C SDK

Enumeration Type Documentation

wc_event_t

enum wc_event_t

Enumerator
WC_EVENT_ADD_FD	WC_EVENT_ADD_FD. This event indicates that a new file descriptor should be polled for some given events. data is a pointer to a struct wc_pollargs object that contains the details on the descriptor and events.
WC_EVENT_DEL_FD	WC_EVENT_DEL_FD. This event indicates that a file descriptor should be removed from the poll set. data is a pointer to a struct wc_pollargs object that contains the details on the descriptor.
WC_EVENT_MODIFY_FD	WC_EVENT_MODIFY_FD. This event indicates that the events to poll for an already polled file file descriptor must be changed. data is a pointer to a struct wc_pollargs object that contains the details on the descriptor and events.
WC_EVENT_SET_TIMER	WC_EVENT_SET_TIMER. This event instructs that a timer whose properties are passed in data as a pointer to a struct wc_timerargs object must be set and armed. When the timer fires, you must call the wc_handle_timer() function, with the appropriate wc_timersrc argument set.
WC_EVENT_DEL_TIMER	WC_EVENT_DEL_TIMER. This event instructs that the timer whose identity is passed in data as a pointer to a enum wc_timersrc must be cancelled.
WC_EVENT_ON_CNX_CLOSED	WC_EVENT_ON_CNX_CLOSED. This event indicates that the connection passed as cnx to the callback was closed, either because the server has closed it, or because wc_cnx_close() was called.
WC_EVENT_ON_SERVER_HANDSHAKE	WC_EVENT_ON_SERVER_HANDSHAKE. This event indicates that the webcom server has sent its handshake message. From this point, it's safe to start sending requests to the webcom server through this connection. Return 1 to trigger automatic reconnection.
WC_EVENT_ON_MSG_RECEIVED	WC_EVENT_ON_MSG_RECEIVED. This event indicates that a valid webcom message was received on the given connection. The parsed message pointer (wc_msg_t *) is passed as (void *)data to the callback.
WC_EVENT_ON_CNX_ERROR	WC_EVENT_ON_CNX_ERROR. This event indicates that an error occurred on the given connection. An additional error string of size len is given in data. Return 1 to trigger automatic reconnection.
WC_AUTH_ON_AUTH_REPLY	WC_AUTH_ON_AUTH_REPLY. This event indicates that a reply to an authentication request is available. The details about the result is passed in data as a pointer to a struct wc_auth_info.

wc_pollsrc

enum wc_pollsrc

the origin of a poll event

Enumerator
WC_POLL_DATASYNC	the event relates to the datasync socket
WC_POLL_AUTH	the event relates to the authentication socket
_WC_POLL_MAX	special value, holds the actual number of possible socket event sources

wc_timersrc

enum wc_timersrc

the origin of a timer event

Enumerator
WC_TIMER_DATASYNC_KEEPALIVE	the event relates to the datasync socket keepalive
WC_TIMER_DATASYNC_RECONNECT	the event relates to the datasync reconnection timer
WC_TIMER_AUTH	the event relates to the authentication HTTP request handling
_WC_TIMER_MAX	special value, holds the actual number of possible timers

Function Documentation

wc_context_create()

wc_context_t* wc_context_create

(

struct wc_context_options *

options

)

creates a Webcom context

This function creates and initializes a new Webcom context using the given options.

Parameters

options

a pointer to a wc_context_options structure with each field set to the desired value

Returns

a pointer to the context (it's an opaque structure)

wc_context_destroy()

void wc_context_destroy

(

wc_context_t *

ctx

)

destoys a Webcom context

This function destroys a wc_context_t object that was previously allocated by the wc_context_create() function.

Parameters

ctx	the context to destroy

wc_context_get_user_data()

void* wc_context_get_user_data

(

wc_context_t *

ctx

)

gets the user data associated to this context

Parameters

ctx	the context

Returns

some user-defined data, set in wc_context_new()

wc_dispatch_fd_event()

void wc_dispatch_fd_event	(	wc_context_t *	ctx,
		struct wc_pollargs *	pa
	)

informs the SDK of some event happening on one of its file descriptors

This function is to be called by the event loop logic to make the Webcom SDK handle any pending event on one of its file descriptor.

Parameters

ctx	the context
pa	a pointer to a structure describing the event (file descriptor, events [WC_POLLHUP, WC_POLLIN, WC_POLLOUT], and source [WC_POLL_DATASYNC, WC_POLL_AUTH])

wc_dispatch_timer_event()

void wc_dispatch_timer_event	(	wc_context_t *	ctx,
		enum wc_timersrc	timer
	)

informs the SDK that some timer has fired

You need to call this function once a timer armed because of a WC_EVENT_SET_TIMER event has fired.

Parameters

ctx	the context
timer	the timer identifier