Handles routing all events to their proper handlers. More...

#include "quickio.h"

Classes
struct	evs_on_info
	Contains all the fields necessary to send a callback to a client about a subscription. More...

struct	event
	Events are stored in a prefix tree for fast, nice lookups. More...

Macros
#define	EVS_NO_CALLBACK (0l)
	The value that indicates there is no callback.

Typedefs
typedef guint64	evs_cb_t
	Callbacks are just gigantic integers, 0 meaning "no callback".

typedef enum evs_status(*	evs_handler_fn )(struct client client, const gchar ev_extra, const evs_cb_t client_cb, gchar *json)
	The handler function type. More...

typedef void(*	evs_off_fn )(struct client client, const gchar ev_extra)
	The handler for when a client unsubscribes. More...

typedef enum evs_status(*	evs_cb_fn )(struct client client, const void data, const evs_cb_t client_cb, gchar *json)
	Function called when the client sends a callback to the server.

typedef enum evs_status(*	evs_on_fn )(const struct evs_on_info *info)
	The handler for when a client subscribes. More...

Enumerations
enum	evs_status { EVS_STATUS_OK, EVS_STATUS_ERR, EVS_STATUS_HANDLED }
	From handlers, these values instruct the server how to handle everything. More...

enum	evs_code { CODE_OK = 200, CODE_ACCEPTED = 202, CODE_BAD = 400, CODE_UNAUTH = 401, CODE_NOT_FOUND = 404, CODE_ENHANCE_CALM = 420, CODE_UNKNOWN = 500 }
	Codes used for callbacks. More...

Functions
void	event_init (struct event ev, const gchar ev_path, const evs_handler_fn handler_fn, const evs_on_fn on_fn, const evs_off_fn off_fn, const gboolean handle_children)
	Intialize a new `struct event`

void	event_clear (struct event *ev)
	Clean up all memory inside a `struct event`

struct event *	evs_add_handler (const gchar ev_prefix, const gchar ev_path, const evs_handler_fn handler_fn, const evs_on_fn on_fn, const evs_off_fn off_fn, const gboolean handle_children)
	Creates a handler for an event. More...

enum evs_status	evs_no_on (const struct evs_on_info *info)
	Doesn't allow anyone to subscribe to the event. More...

guint	evs_clean_path (gchar *ev_path)
	Given an arbitrary, full path, clean it up entirely (in place) so that it conforms with QIO standards. More...

GString *	evs_make_path (const gchar ev_prefix, const gchar ev_path, const gchar *ev_extra)
	Given a path, make it such that is matches exactly what QIO expects paths to be. More...

void	evs_route (struct client client, gchar ev_path, const evs_cb_t client_cb, gchar *json)
	Routes an event from a client. More...

void	evs_on (struct client client, struct event ev, gchar *ev_extra, const evs_cb_t client_cb)
	Subscribes the client to the event, checking with the event's subscriber callback that such things are allowed. More...

void	evs_send (struct client client, struct event ev, const gchar ev_extra, const gchar json)
	Sends an event to a specific client. More...

void	evs_send_info (const struct evs_on_info info, const gchar json)
	Sends an event to a specific client. More...

void	evs_send_sub (struct client client, struct subscription sub, const gchar *json)
	Sends an event to a specific client. More...

void	evs_send_full (struct client client, struct event ev, const gchar ev_extra, const gchar json, const evs_cb_fn cb_fn, void *cb_data, const qev_free_fn free_fn)
	Sends an event to a specific client, requesting a callback from the client. More...

void	evs_send_info_full (const struct evs_on_info info, const gchar json, const evs_cb_fn cb_fn, void *cb_data, const qev_free_fn free_fn)
	Sends an event to a specific client, requesting a callback from the client. More...

void	evs_send_sub_full (struct client client, struct subscription sub, const gchar json, const evs_cb_fn cb_fn, void cb_data, const qev_free_fn free_fn)
	Sends an event to a specific client, requesting a callback from the client. More...

void	evs_send_bruteforce (struct client client, const gchar ev_prefix, const gchar ev_path, const gchar ev_extra, const gchar json, const evs_cb_fn cb_fn, void cb_data, const qev_free_fn free_fn)
	Send an event to a client, damn the consequences. More...

void	evs_on_cb (const gboolean success, const struct evs_on_info *info)
	Subscribes a client to an event without any callback checks. More...

struct evs_on_info *	evs_on_info_copy (const struct evs_on_info *info, const gboolean with_ev_extra)
	Make a copy of the evs_on_info(), returning a reference that is safe to use from another thread. More...

void	evs_on_info_free (struct evs_on_info *info)
	Clean up the copy of struct evs_on_info, releasing any references made. More...

void	evs_off (struct client client, struct event ev, const gchar *ev_extra)
	Remove a client from an event. More...

void	evs_client_offd (struct client client, struct subscription sub)
	The client was unsubscribed from an event, and any callbacks should be fired immediately. More...

void	evs_cb (struct client client, const evs_cb_t client_cb, const gchar json)
	Sends a CODE_OK callback to a client. More...

void	evs_cb_with_cb (struct client client, const evs_cb_t client_cb, const gchar json, const evs_cb_fn cb_fn, void *cb_data, const qev_free_fn free_fn)
	Sends a CODE_OK callback to a client while requesting a callback from the client. More...

void	evs_err_cb (struct client client, const evs_cb_t client_cb, const enum evs_code code, const gchar err_msg, const gchar *json)
	Sends a callback to a client with an error code and message. More...

void	evs_cb_full (struct client client, const evs_cb_t client_cb, const enum evs_code code, const gchar err_msg, const gchar json, const evs_cb_fn cb_fn, void cb_data, const qev_free_fn free_fn)
	Sends a callback to a client, with all possible data. More...

void	evs_broadcast (struct event ev, const gchar ev_extra, const gchar *json)
	Broadcast a message to all clients listening on the event. More...

void	evs_client_close (struct client *client)
	Cleans up after the client when it closes.

void	evs_broadcast_path (const gchar ev_path, const gchar json)
	Broadcast a message to all clients listening on the event. More...

void	evs_broadcast_tick ()
	Do the actual event broadcasting. More...

void	evs_pre_init ()
	Initialize events. More...

void	evs_init ()
	Initialize the stats in events.

Detailed Description

Handles routing all events to their proper handlers.

Author: Andrew Stone andre.nosp@m.w@cl.nosp@m.ovar..nosp@m.com

Copyright: 2012-2014 Clear Channel Inc.

Typedef Documentation

typedef enum evs_status(* evs_handler_fn)(struct client *client, const gchar *ev_extra, const evs_cb_t client_cb, gchar *json)

The handler function type.

Parameters

client The client that triggered the event.

typedef void(* evs_off_fn)(struct client *client, const gchar *ev_extra)

The handler for when a client unsubscribes.

Parameters

client The client that unsubscribed.

typedef enum evs_status(* evs_on_fn)(const struct evs_on_info *info)

The handler for when a client subscribes.

Parameters

info	A self-contained struct of info that can be hurled around; contains all information needed to send a subscribe callback to a client. If you intend on returning EVS_STATUS_HANDLED and are passing this struct to another thread or using it anywhere else, you MUST use qio.evs_on_info_copy() to make sure all references this struct contains are usable (qio.evs_on_info_free() cleans it all up).
ev_extra	Any extra paramters that came with the subscription

Returns: What should be done with the subscription.

Enumeration Type Documentation

enum evs_code

Codes used for callbacks.

We're not doing anything HTTP with QIO, but the HTTP error codes are pretty well know, so reusing what already exists just makes more sense.

Enumerator
CODE_OK	Everything went as expected.
CODE_ACCEPTED	A previous request for the exact same thing is currently being processed.
CODE_BAD	Malformed data was sent. It's not fatal, just annoying.
CODE_UNAUTH	You're not allowed to do that.
CODE_NOT_FOUND	Yeah, I'm going to need you to go ahead and not use something that doesn't exist.
CODE_ENHANCE_CALM	The server understood the request but needs to client to calm down. Aka. you've been rate-limited.
CODE_UNKNOWN	An unknown error occurred.

enum evs_status

From handlers, these values instruct the server how to handle everything.

Enumerator

EVS_STATUS_OK

The event was handled and a default callback should be sent, if the client requested.

For subscriptions, this indicates that a subscription is valid and should be accepted.

EVS_STATUS_ERR

There was an error with the handler and a generic error should be sent back to the client.

For subscriptions, this indicates that a subscription is invalid and should be rejected.

EVS_STATUS_HANDLED

The event was handled and any necessary callbacks (including error callbacks) have been dispatched by the handler / are going to be dispatched in the future when data becomes available.

For subscriptions, this indicates that the subscription_handler has already / will dispatch the correct subscription callbacks when it can.

Function Documentation

struct event* evs_add_handler	(	const gchar *	ev_prefix,
		const gchar *	ev_path,
		const evs_handler_fn	handler_fn,
		const evs_on_fn	on_fn,
		const evs_off_fn	off_fn,
		const gboolean	handle_children
	)

Creates a handler for an event.

Parameters

ev_prefix	A prefix to add to the event path
ev_path	The path for the event
handler_fn	The function that handles the event
on_fn	Before a subscription is created, this will be called to check if the subscription should be allowed.
off_fn	Called when a client unsubscribes
handle_children	If this event handler also handles sub-events. For example, if your event is /test/event, then it would receive events of /test/event/path, /test/event/other, /test/event/more.

void evs_broadcast	(	struct event *	ev,
		const gchar *	ev_extra,
		const gchar *	json
	)

Broadcast a message to all clients listening on the event.

Parameters

ev	The event to broadcast to
ev_extra	Any extra path segments
json	The json to send to everyone

void evs_broadcast_path	(	const gchar *	ev_path,
		const gchar *	json
	)

Broadcast a message to all clients listening on the event.

Parameters

ev_path	The path to broadcast to
json	The json to send to everyone

void evs_broadcast_tick ( )

Do the actual event broadcasting.

Note: This may only be called from a QEV thread.

void evs_cb	(	struct client *	client,
		const evs_cb_t	client_cb,
		const gchar *	json
	)

Sends a CODE_OK callback to a client.

Parameters

client	The client to send the callback to
client_cb	The ID of the callback to send
json	Any data to include with the callback

void evs_cb_full	(	struct client *	client,
		const evs_cb_t	client_cb,
		const enum evs_code	code,
		const gchar *	err_msg,
		const gchar *	json,
		const evs_cb_fn	cb_fn,
		void *	cb_data,
		const qev_free_fn	free_fn
	)

Sends a callback to a client, with all possible data.

Attention: It is understood that, if a non CODE_OK callback is sent, the server MAY NOT expect a callback from the client.

Parameters

client	The client to send the callback to
client_cb	The ID of the callback to send
code	Any response code you want to send. There are the standard ones, but you're free to use whatever you want (including negative ones). Keep in mind that `err_msg` is only sent with the callback when code != 200.
err_msg	An error message to send with the callback if code != 200.
json	Any data to include with the callback
cb_fn	The function to be called when the client responds to the server callback.
cb_data	Data to be given back to the callback when the client responds [transfer-full]
free_fn	Function that frees cb_data

void evs_cb_with_cb	(	struct client *	client,
		const evs_cb_t	client_cb,
		const gchar *	json,
		const evs_cb_fn	cb_fn,
		void *	cb_data,
		const qev_free_fn	free_fn
	)

Sends a CODE_OK callback to a client while requesting a callback from the client.

Parameters

client	The client to send the callback to
client_cb	The ID of the callback to send
json	Any data to include with the callback
cb_fn	The function to be called when the client responds to the server callback. [allow-null]
cb_data	Data to be given back to the callback when the client responds [transfer-full]
free_fn	Function that frees cb_data [allow-null]

guint evs_clean_path ( gchar * ev_path )

Given an arbitrary, full path, clean it up entirely (in place) so that it conforms with QIO standards.

Parameters

ev_path The path to clean up

Returns: The length of the cleaned path

void evs_client_offd	(	struct client *	client,
		struct subscription *	sub
	)

The client was unsubscribed from an event, and any callbacks should be fired immediately.

You should be holding a lock on the client while do unsubscribe operations.

Parameters

client	The client that was removed
sub	The subscription that the client was removed from

void evs_err_cb	(	struct client *	client,
		const evs_cb_t	client_cb,
		const enum evs_code	code,
		const gchar *	err_msg,
		const gchar *	json
	)

Sends a callback to a client with an error code and message.

Parameters

client	The client to send the callback to
client_cb	The ID of the callback to send
code	Any response code you want to send. There are the standard ones, but you're free to use whatever you want. Keep in mind that `err_msg` is only sent with the callback when code != 200.
err_msg	An error message to send with the callback if code != 200.
json	Any data to include with the callback

GString* evs_make_path	(	const gchar *	ev_prefix,
		const gchar *	ev_path,
		const gchar *	ev_extra
	)

Given a path, make it such that is matches exactly what QIO expects paths to be.

Parameters

ev_prefix	The prefix to prepend to the path
ev_path	The event path
ev_extra	Any extra path segments

Returns: The cleaned path. qev_buffer_put when you're done with it. [transfer-full]

enum evs_status evs_no_on ( const struct evs_on_info * info )

Doesn't allow anyone to subscribe to the event.

Use this for qio.add_handler for the on_fn to disable subscriptions to the event.

void evs_off	(	struct client *	client,
		struct event *	ev,
		const gchar *	ev_extra
	)

Remove a client from an event.

Parameters

client	The client to unsubscribe from the event
ev	The event to remove the client from
ev_extra	Any extra path segments

void evs_on	(	struct client *	client,
		struct event *	ev,
		gchar *	ev_extra,
		const evs_cb_t	client_cb
	)

Subscribes the client to the event, checking with the event's subscriber callback that such things are allowed.

Parameters

client	The client to subscribe to the event
ev	The event to add the client to
ev_extra	Any extra path segments
client_cb	The id of the callback to send to the client

void evs_on_cb	(	const gboolean	success,
		const struct evs_on_info *	info
	)

Subscribes a client to an event without any callback checks.

This should only be used in the callback case.

Parameters

success	If the checks were successful and the client should be added to the subscription. An error callback is sent if false.
info	The callback information, originally given with the callback

struct evs_on_info* evs_on_info_copy	(	const struct evs_on_info *	info,
		const gboolean	with_ev_extra
	)

Make a copy of the evs_on_info(), returning a reference that is safe to use from another thread.

Parameters

info	The object to make a copy of. Also ensures that all references necessary are made before returning.
with_ev_extra	If you want ev_extra in the copy. By default, info->ev_extra is left NULL;

void evs_on_info_free ( struct evs_on_info * info )

Clean up the copy of struct evs_on_info, releasing any references made.

Parameters

info	The data to free up. Makes sure that all things inside are unreferenced properly.

void evs_pre_init ( )

Initialize events.

There are two init calls here because events need to persist for the life of the server. If events aren't the LAST things torn down, QEV might close clients after events have been freed, thus causing invalid accesses to freed events.

void evs_route	(	struct client *	client,
		gchar *	ev_path,
		const evs_cb_t	client_cb,
		gchar *	json
	)

Routes an event from a client.

Parameters

client	The client that sent the event
ev_path	The path of the event
client_cb	If not 0, the client wants a response to this event sent to the callback of that id.
json	Any JSON data included with the event. May NOT be null.

void evs_send	(	struct client *	client,
		struct event *	ev,
		const gchar *	ev_extra,
		const gchar *	json
	)

Sends an event to a specific client.

Parameters

client	The client to send the event to
ev	The event to send
ev_extra	Any extra path segments for the event
json	Any data to include with the event

void evs_send_bruteforce	(	struct client *	client,
		const gchar *	ev_prefix,
		const gchar *	ev_path,
		const gchar *	ev_extra,
		const gchar *	json,
		const evs_cb_fn	cb_fn,
		void *	cb_data,
		const qev_free_fn	free_fn
	)

Send an event to a client, damn the consequences.

Note: This is a brute-force function that's really only useful when sending internal QIO events that don't go by the general rules of other events.

Parameters

client	The client to send the event to
ev_prefix	A prefix to add to the event path
ev_path	The event path to brute force
ev_extra	Any extra segments
json	Data to include
cb_fn	Function to execute on callback
cb_data	Data to pass into the function [transfer-full]
free_fn	Frees the cb_data

void evs_send_full	(	struct client *	client,
		struct event *	ev,
		const gchar *	ev_extra,
		const gchar *	json,
		const evs_cb_fn	cb_fn,
		void *	cb_data,
		const qev_free_fn	free_fn
	)

Sends an event to a specific client, requesting a callback from the client.

Parameters

client	The client to send the callback to
ev	The event to send
ev_extra	Any extra path segments for the event
json	Any data to include with the event
cb_fn	The function to execute on callback
cb_data	Data to pass into the function [transfer-full]
free_fn	Frees the cb_data

void evs_send_info	(	const struct evs_on_info *	info,
		const gchar *	json
	)

Sends an event to a specific client.

Parameters

info	The event info, typically from an event subscription.
json	Any data to include with the event

void evs_send_info_full	(	const struct evs_on_info *	info,
		const gchar *	json,
		const evs_cb_fn	cb_fn,
		void *	cb_data,
		const qev_free_fn	free_fn
	)

Sends an event to a specific client, requesting a callback from the client.

Parameters

info	The event info, typically from an event subscription.
json	Any data to include with the event
cb_fn	The function to execute on callback
cb_data	Data to pass into the function [transfer-full]
free_fn	Frees the cb_data

void evs_send_sub	(	struct client *	client,
		struct subscription *	sub,
		const gchar *	json
	)

Sends an event to a specific client.

Parameters

client	The client to send the event to
sub	The subscription that references the event being sent to the client.
json	Any data to include with the event

void evs_send_sub_full	(	struct client *	client,
		struct subscription *	sub,
		const gchar *	json,
		const evs_cb_fn	cb_fn,
		void *	cb_data,
		const qev_free_fn	free_fn
	)

Sends an event to a specific client, requesting a callback from the client.

Parameters

client	The client to send the callback to
sub	The subscription that references the event being sent to the client.
json	Any data to include with the event
cb_fn	The function to execute on callback
cb_data	Data to pass into the function [transfer-full]
free_fn	Frees the cb_data

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation