presencestate.h File Reference

Presence state management. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	ast_presence_state_message
	Stasis message payload representing a presence state update. More...

Typedefs
typedef enum ast_presence_state(*	ast_presence_state_prov_cb_type) (const char *data, char **subtype, char **message)
	Presence state provider call back. More...

Enumerations
enum	ast_presence_state {   AST_PRESENCE_NOT_SET = 0, AST_PRESENCE_UNAVAILABLE, AST_PRESENCE_AVAILABLE, AST_PRESENCE_AWAY,   AST_PRESENCE_XA, AST_PRESENCE_CHAT, AST_PRESENCE_DND, AST_PRESENCE_INVALID }

Functions
enum ast_presence_state	ast_presence_state (const char *presence_provider, char **subtype, char **message)
	Asks a presence state provider for the current presence state. More...
const char *	ast_presence_state2str (enum ast_presence_state state)
	Convert presence state to text string for output. More...
struct stasis_cache *	ast_presence_state_cache (void)
	Backend cache for ast_presence_state_topic_cached() More...
int	ast_presence_state_changed (enum ast_presence_state state, const char *subtype, const char *message, const char *fmt,...)
	Notify the world that a presence provider state changed. More...
int	ast_presence_state_changed_literal (enum ast_presence_state state, const char *subtype, const char *message, const char *presence_provider)
	Notify the world that a presence provider state changed. More...
int	ast_presence_state_engine_init (void)
struct stasis_message_type *	ast_presence_state_message_type (void)
	Get presence state message type. More...
enum ast_presence_state	ast_presence_state_nocache (const char *presence_provider, char **subtype, char **message)
	Asks a presence state provider for the current presence state, bypassing the event cache. More...
int	ast_presence_state_prov_add (const char *label, ast_presence_state_prov_cb_type callback)
	Add presence state provider. More...
int	ast_presence_state_prov_del (const char *label)
	Remove presence state provider. More...
struct stasis_topic *	ast_presence_state_topic_all (void)
	Get presence state topic. More...
struct stasis_topic *	ast_presence_state_topic_cached (void)
	Get caching presence state topic. More...
enum ast_presence_state	ast_presence_state_val (const char *val)
	Convert presence state from text to integer value. More...

Detailed Description

Presence state management.

Definition in file presencestate.h.

Typedef Documentation

ast_presence_state_prov_cb_type

typedef enum ast_presence_state(* ast_presence_state_prov_cb_type) (const char *data, char **subtype, char **message)

Presence state provider call back.

Definition at line 43 of file presencestate.h.

Enumeration Type Documentation

ast_presence_state

enum ast_presence_state

Enumerator
AST_PRESENCE_NOT_SET
AST_PRESENCE_UNAVAILABLE
AST_PRESENCE_AVAILABLE
AST_PRESENCE_AWAY
AST_PRESENCE_XA
AST_PRESENCE_CHAT
AST_PRESENCE_DND
AST_PRESENCE_INVALID

Definition at line 26 of file presencestate.h.

                        {
   AST_PRESENCE_NOT_SET = 0,
   AST_PRESENCE_UNAVAILABLE,
   AST_PRESENCE_AVAILABLE,
   AST_PRESENCE_AWAY,
   AST_PRESENCE_XA,
   AST_PRESENCE_CHAT,
   AST_PRESENCE_DND,
   /* This is not something that a user can
    * set his presence to. Rather, this is returned
    * to indicate that presence is in some invalid
    * state
    */
   AST_PRESENCE_INVALID,
};

Function Documentation

ast_presence_state()

enum ast_presence_state ast_presence_state	(	const char *	presence_provider,
		char **	subtype,
		char **	message
	)

Asks a presence state provider for the current presence state.

Parameters

presence_provider	The presence provider to retrieve the state from.
subtype	The output paramenter to store the subtype string in. Must be freed if returned
message	The output paramenter to store the message string in. Must be freed if returned

Return values

presence	state value on success,
-1	on failure.

Definition at line 221 of file presencestate.c.

References ast_presence_state_helper().

{
   return ast_presence_state_helper(presence_provider, subtype, message, 1);
}

ast_presence_state2str()

const char* ast_presence_state2str

(

enum ast_presence_state

state

)

Convert presence state to text string for output.

Parameters

state

Current presence state

Definition at line 103 of file presencestate.c.

References ARRAY_LEN, and state2string.

Referenced by action_presencestate(), AST_TEST_DEFINE(), exten_state_publisher_state_cb(), handle_cli_presencestate_list(), handle_show_hint(), handle_show_hints(), manager_state_cb(), pidf_supplement_body(), presence_change_common(), presence_read(), presence_state_to_ami(), and state_notify_build_xml().

{
   int i;
   for (i = 0; i < ARRAY_LEN(state2string); i++) {
      if (state == state2string[i].state) {
         return state2string[i].string;
      }
   }
   return "";
}

ast_presence_state_cache()

struct stasis_cache* ast_presence_state_cache

(

void

)

Backend cache for ast_presence_state_topic_cached()

Return values

Cache

of ast_presence_state_message.

Since

12

Definition at line 370 of file presencestate.c.

References presence_state_cache.

Referenced by action_presencestatelist(), and presence_state_cached().

{
   return presence_state_cache;
}

ast_presence_state_changed()

int ast_presence_state_changed	(	enum ast_presence_state	state,
		const char *	subtype,
		const char *	message,
		const char *	fmt,
			...
	)

Notify the world that a presence provider state changed.

Parameters

state	the new presence state
subtype	the new presence subtype
message	the new presence message
fmt	Presence entity whose state has changed

The new state of the entity will be sent off to any subscribers of the presence state. It will also be stored in the internal event cache.

Return values

0	Success
-1	Failure

Definition at line 350 of file presencestate.c.

References AST_MAX_EXTENSION, ast_presence_state_changed_literal(), and buf.

Referenced by load_module().

{
   char buf[AST_MAX_EXTENSION];
   va_list ap;

   va_start(ap, fmt);
   vsnprintf(buf, sizeof(buf), fmt, ap);
   va_end(ap);

   return ast_presence_state_changed_literal(state, subtype, message, buf);
}

ast_presence_state_changed_literal()

int ast_presence_state_changed_literal	(	enum ast_presence_state	state,
		const char *	subtype,
		const char *	message,
		const char *	presence_provider
	)

Notify the world that a presence provider state changed.

Parameters

state	the new presence state
subtype	the new presence subtype
message	the new presence message
presence_provider	Presence entity whose state has changed

The new state of the entity will be sent off to any subscribers of the presence state. It will also be stored in the internal event cache.

Return values

0	Success
-1	Failure

Definition at line 336 of file presencestate.c.

References AST_PRESENCE_NOT_SET, do_presence_state_change(), and presence_state_event().

Referenced by ast_presence_state_changed(), handle_cli_presencestate_change(), and presence_write().

{
   if (state == AST_PRESENCE_NOT_SET) {
      do_presence_state_change(presence_provider);
   } else {
      presence_state_event(presence_provider, state, subtype, message);
   }

   return 0;
}

ast_presence_state_engine_init()

int ast_presence_state_engine_init

(

void

)

Definition at line 495 of file presencestate.c.

References ast_presence_state_message_type(), ast_register_cleanup(), AST_TEST_REGISTER, presence_state_engine_cleanup(), presence_state_get_id(), stasis_cache_create(), stasis_caching_accept_message_type(), stasis_caching_set_filter(), stasis_caching_topic_create(), STASIS_MESSAGE_TYPE_INIT, STASIS_SUBSCRIPTION_FILTER_SELECTIVE, and stasis_topic_create().

Referenced by asterisk_daemon().

{
   ast_register_cleanup(presence_state_engine_cleanup);

   if (STASIS_MESSAGE_TYPE_INIT(ast_presence_state_message_type) != 0) {
      return -1;
   }

   presence_state_topic_all = stasis_topic_create("presence_state:all");
   if (!presence_state_topic_all) {
      return -1;
   }

   presence_state_cache = stasis_cache_create(presence_state_get_id);
   if (!presence_state_cache) {
      return -1;
   }

   presence_state_topic_cached = stasis_caching_topic_create(presence_state_topic_all, presence_state_cache);
   if (!presence_state_topic_cached) {
      return -1;
   }
   stasis_caching_accept_message_type(presence_state_topic_cached, ast_presence_state_message_type());
   stasis_caching_set_filter(presence_state_topic_cached, STASIS_SUBSCRIPTION_FILTER_SELECTIVE);

   AST_TEST_REGISTER(test_presence_chan);

   return 0;
}

ast_presence_state_message_type()

struct stasis_message_type* ast_presence_state_message_type

(

void

)

Get presence state message type.

Return values

Stasis

message type for presence state messages

Since

12

Referenced by action_presencestatelist(), ast_presence_state_engine_init(), load_pbx(), presence_state_cached(), presence_state_cb(), presence_state_engine_cleanup(), presence_state_event(), presence_state_get_id(), and test_cb().

ast_presence_state_nocache()

enum ast_presence_state ast_presence_state_nocache	(	const char *	presence_provider,
		char **	subtype,
		char **	message
	)

Asks a presence state provider for the current presence state, bypassing the event cache.

Some presence state providers may perform transformations on presence data when it is requested (such as a base64 decode). In such instances, use of the event cache is not suitable and should be bypassed.

Parameters

presence_provider	The presence provider to retrieve the state from.
subtype	The output paramenter to store the subtype string in. Must be freed if returned
message	The output paramenter to store the message string in. Must be freed if returned

Return values

presence	state value on success,
-1	on failure.

Definition at line 226 of file presencestate.c.

References ast_presence_state_helper().

Referenced by AST_TEST_DEFINE(), and presence_read().

{
   return ast_presence_state_helper(presence_provider, subtype, message, 0);
}

ast_presence_state_prov_add()

int ast_presence_state_prov_add	(	const char *	label,
		ast_presence_state_prov_cb_type	callback
	)

Add presence state provider.

Parameters

label	to use in hint, like label:object
callback	Callback

Return values

0	success
-1	failure

Definition at line 231 of file presencestate.c.

References ast_calloc, ast_copy_string(), AST_RWLIST_INSERT_HEAD, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, presence_state_provider::callback, presence_state_provider::label, and provider.

Referenced by load_module().

{
   struct presence_state_provider *provider;

   if (!callback || !(provider = ast_calloc(1, sizeof(*provider)))) {
      return -1;
   }

   provider->callback = callback;
   ast_copy_string(provider->label, label, sizeof(provider->label));

   AST_RWLIST_WRLOCK(&presence_state_providers);
   AST_RWLIST_INSERT_HEAD(&presence_state_providers, provider, list);
   AST_RWLIST_UNLOCK(&presence_state_providers);

   return 0;
}

ast_presence_state_prov_del()

int ast_presence_state_prov_del

(

const char *

label

)

Remove presence state provider.

Parameters

label

to use in hint, like label:object

Return values

-1	on failure
0	on success

Definition at line 248 of file presencestate.c.

References ast_free, AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, presence_state_provider::label, and provider.

Referenced by unload_module().

{
   struct presence_state_provider *provider;
   int res = -1;

   AST_RWLIST_WRLOCK(&presence_state_providers);
   AST_RWLIST_TRAVERSE_SAFE_BEGIN(&presence_state_providers, provider, list) {
      if (!strcasecmp(provider->label, label)) {
         AST_RWLIST_REMOVE_CURRENT(list);
         ast_free(provider);
         res = 0;
         break;
      }
   }
   AST_RWLIST_TRAVERSE_SAFE_END;
   AST_RWLIST_UNLOCK(&presence_state_providers);

   return res;
}

ast_presence_state_topic_all()

struct stasis_topic* ast_presence_state_topic_all

(

void

)

Get presence state topic.

Return values

Stasis

topic for presence state messages

Since

12

Definition at line 365 of file presencestate.c.

References presence_state_topic_all.

Referenced by load_module(), load_pbx(), presence_change_common(), presence_state_event(), and publish_hint_change().

{
   return presence_state_topic_all;
}

ast_presence_state_topic_cached()

struct stasis_topic* ast_presence_state_topic_cached

(

void

)

Get caching presence state topic.

Return values

Caching

Stasis topic for presence state messages

Since

12

Definition at line 375 of file presencestate.c.

References stasis_caching_get_topic().

{
   return stasis_caching_get_topic(presence_state_topic_cached);
}

ast_presence_state_val()

enum ast_presence_state ast_presence_state_val

(

const char *

val

)

Convert presence state from text to integer value.

Parameters

val	The text representing the presence state. Valid values are anything that comes after AST_PRESENCE_ in one of the defined values.

Returns

The AST_PRESENCE_ integer value

Definition at line 114 of file presencestate.c.

References ARRAY_LEN, AST_PRESENCE_INVALID, and state2string.

Referenced by parse_data().

{
   int i;
   for (i = 0; i < ARRAY_LEN(state2string); i++) {
      if (!strcasecmp(val, state2string[i].string)) {
         return state2string[i].state;
      }
   }
   return AST_PRESENCE_INVALID;
}