diff options
Diffstat (limited to 'include/asterisk')
-rw-r--r-- | include/asterisk/app.h | 58 | ||||
-rw-r--r-- | include/asterisk/app_voicemail.h | 212 | ||||
-rw-r--r-- | include/asterisk/callerid.h | 1 | ||||
-rw-r--r-- | include/asterisk/config.h | 57 | ||||
-rw-r--r-- | include/asterisk/event_defs.h | 10 | ||||
-rw-r--r-- | include/asterisk/file.h | 38 | ||||
-rw-r--r-- | include/asterisk/manager.h | 2 | ||||
-rw-r--r-- | include/asterisk/message.h | 30 | ||||
-rw-r--r-- | include/asterisk/pbx.h | 34 | ||||
-rw-r--r-- | include/asterisk/presencestate.h | 154 | ||||
-rw-r--r-- | include/asterisk/sip_api.h | 51 |
11 files changed, 641 insertions, 6 deletions
diff --git a/include/asterisk/app.h b/include/asterisk/app.h index edf1c1c37..d438790e3 100644 --- a/include/asterisk/app.h +++ b/include/asterisk/app.h @@ -23,8 +23,10 @@ #ifndef _ASTERISK_APP_H #define _ASTERISK_APP_H +#include "asterisk/stringfields.h" #include "asterisk/strings.h" #include "asterisk/threadstorage.h" +#include "asterisk/file.h" struct ast_flags64; @@ -77,6 +79,27 @@ struct ast_ivr_menu { unsigned int flags; /*!< Flags */ struct ast_ivr_option *options; /*!< All options */ }; + +/*! + * \brief Structure used for ast_copy_recording_to_vm in order to cleanly supply + * data needed for making the recording from the recorded file. + */ +struct ast_vm_recording_data { + AST_DECLARE_STRING_FIELDS( + AST_STRING_FIELD(context); + AST_STRING_FIELD(mailbox); + AST_STRING_FIELD(folder); + AST_STRING_FIELD(recording_file); + AST_STRING_FIELD(recording_ext); + + AST_STRING_FIELD(call_context); + AST_STRING_FIELD(call_macrocontext); + AST_STRING_FIELD(call_extension); + AST_STRING_FIELD(call_callerchan); + AST_STRING_FIELD(call_callerid); + ); + int call_priority; +}; #define AST_IVR_FLAG_AUTORESTART (1 << 0) @@ -219,11 +242,21 @@ void ast_install_vm_functions(int (*has_voicemail_func)(const char *mailbox, con int (*inboxcount_func)(const char *mailbox, int *newmsgs, int *oldmsgs), int (*inboxcount2_func)(const char *mailbox, int *urgentmsgs, int *newmsgs, int *oldmsgs), int (*messagecount_func)(const char *context, const char *mailbox, const char *folder), - int (*sayname_func)(struct ast_channel *chan, const char *mailbox, const char *context)); + int (*sayname_func)(struct ast_channel *chan, const char *mailbox, const char *context), + int (*copy_recording_to_vm_func)(struct ast_vm_recording_data *vm_rec_data)); + void ast_uninstall_vm_functions(void); /*! + * \brief + * param[in] vm_rec_data Contains data needed to make the recording. + * retval 0 voicemail successfully created from recording. + * retval -1 Failure + */ +int ast_app_copy_recording_to_vm(struct ast_vm_recording_data *vm_rec_data); + +/*! * \brief Determine if a given mailbox has any voicemail * If folder is NULL, defaults to "INBOX". If folder is "INBOX", includes the * number of messages in the "Urgent" folder. @@ -339,6 +372,29 @@ int ast_linear_stream(struct ast_channel *chan, const char *filename, int fd, in */ int ast_control_streamfile(struct ast_channel *chan, const char *file, const char *fwd, const char *rev, const char *stop, const char *pause, const char *restart, int skipms, long *offsetms); +/*! + * \brief Stream a file with fast forward, pause, reverse, restart. + * \param chan + * \param file filename + * \param fwd, rev, stop, pause, restart, skipms, offsetms + * \param waitstream callback to invoke when fastforward or rewind occurrs. + * + * Before calling this function, set this to be the number + * of ms to start from the beginning of the file. When the function + * returns, it will be the number of ms from the beginning where the + * playback stopped. Pass NULL if you don't care. + */ +int ast_control_streamfile_w_cb(struct ast_channel *chan, + const char *file, + const char *fwd, + const char *rev, + const char *stop, + const char *pause, + const char *restart, + int skipms, + long *offsetms, + ast_waitstream_fr_cb cb); + /*! \brief Play a stream and wait for a digit, returning the digit that was pressed */ int ast_play_and_wait(struct ast_channel *chan, const char *fn); diff --git a/include/asterisk/app_voicemail.h b/include/asterisk/app_voicemail.h new file mode 100644 index 000000000..8a42bd7bb --- /dev/null +++ b/include/asterisk/app_voicemail.h @@ -0,0 +1,212 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 2011, Digium, Inc. + * + * David Vossel <dvossel@digium.com> + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ + +/*! \file + * \brief Voice Mail API + * \author David Vossel <dvossel@digium.com> + */ + +#ifndef _ASTERISK_VM_H +#define _ASTERISK_VM_H + +#include "asterisk/stringfields.h" +#include "asterisk/linkedlists.h" + +#define AST_VM_FOLDER_NUMBER 12 + +enum ast_vm_snapshot_sort_val { + AST_VM_SNAPSHOT_SORT_BY_ID = 0, + AST_VM_SNAPSHOT_SORT_BY_TIME, +}; + +struct ast_vm_msg_snapshot { + AST_DECLARE_STRING_FIELDS( + AST_STRING_FIELD(msg_id); + AST_STRING_FIELD(callerid); + AST_STRING_FIELD(callerchan); + AST_STRING_FIELD(exten); + AST_STRING_FIELD(origdate); + AST_STRING_FIELD(origtime); + AST_STRING_FIELD(duration); + AST_STRING_FIELD(folder_name); + AST_STRING_FIELD(flag); + ); + unsigned int msg_number; + + AST_LIST_ENTRY(ast_vm_msg_snapshot) msg; +}; + +struct ast_vm_mailbox_snapshot { + int total_msg_num; + AST_LIST_HEAD_NOLOCK(, ast_vm_msg_snapshot) snapshots[AST_VM_FOLDER_NUMBER]; +}; + +/* + * \brief Create a snapshot of a mailbox which contains information about every msg. + * + * \param mailbox, the mailbox to look for + * \param context, the context to look for the mailbox in + * \param folder, OPTIONAL. When not NULL only msgs from the specified folder will be included. + * \param desending, list the msgs in descending order rather than ascending order. + * \param combine_INBOX_and_OLD, When this argument is set, The OLD folder will be represented + * in the INBOX folder of the snapshot. This allows the snapshot to represent the + * OLD and INBOX messages in sorted order merged together. + * + * \retval snapshot on success + * \retval NULL on failure + */ +struct ast_vm_mailbox_snapshot *ast_vm_mailbox_snapshot_create(const char *mailbox, + const char *context, + const char *folder, + int descending, + enum ast_vm_snapshot_sort_val sort_val, + int combine_INBOX_and_OLD); + +/* + * \brief destroy a snapshot + * + * \param mailbox_snapshot The snapshot to destroy. + * \retval NULL + */ +struct ast_vm_mailbox_snapshot *ast_vm_mailbox_snapshot_destroy(struct ast_vm_mailbox_snapshot *mailbox_snapshot); + +/*! + * \brief Move messages from one folder to another + * + * \param mailbox The mailbox to which the folders belong + * \param context The voicemail context for the mailbox + * \param num_msgs The number of messages to move + * \param oldfolder The folder from where messages should be moved + * \param old_msg_nums The message IDs of the messages to move + * \param newfolder The folder to which messages should be moved + * \param new_msg_ids[out] An array of message IDs for the messages as they are in the + * new folder. This array must be num_msgs sized. + * + * \retval -1 Failure + * \retval 0 Success + */ +int ast_vm_msg_move(const char *mailbox, + const char *context, + size_t num_msgs, + const char *oldfolder, + const char *old_msg_ids [], + const char *newfolder); + +/*! + * \brief Remove/delete messages from a mailbox folder. + * + * \param mailbox The mailbox from which to delete messages + * \param context The voicemail context for the mailbox + * \param num_msgs The number of messages to delete + * \param folder The folder from which to remove messages + * \param msgs The message IDs of the messages to delete + * + * \retval -1 Failure + * \retval 0 Success + */ +int ast_vm_msg_remove(const char *mailbox, + const char *context, + size_t num_msgs, + const char *folder, + const char *msgs []); + +/*! + * \brief forward a message from one mailbox to another. + * + * \brief from_mailbox The original mailbox the message is being forwarded from + * \brief from_context The voicemail context of the from_mailbox + * \brief from_folder The folder from which the message is being forwarded + * \brief to_mailbox The mailbox to forward the message to + * \brief to_context The voicemail context of the to_mailbox + * \brief to_folder The voicemail folder to forward the message to + * \brief num_msgs The number of messages being forwarded + * \brief msg_ids The message IDs of the messages in from_mailbox to forward + * \brief delete_old If non-zero, the forwarded messages are also deleted from from_mailbox. + * Otherwise, the messages will remain in the from_mailbox. + * + * \retval -1 Failure + * \retval 0 Success + */ +int ast_vm_msg_forward(const char *from_mailbox, + const char *from_context, + const char *from_folder, + const char *to_mailbox, + const char *to_context, + const char *to_folder, + size_t num_msgs, + const char *msg_ids [], + int delete_old); + +/*! + * \brief Voicemail playback callback function definition + * + * \param channel to play the file back on. + * \param location of file on disk + * \param duration of file in seconds. This will be zero if msg is very short or + * has an unknown duration. + */ +typedef void (ast_vm_msg_play_cb)(struct ast_channel *chan, const char *playfile, int duration); + +/*! + * \brief Play a voicemail msg back on a channel. + * + * \param mailbox msg is in. + * \param context of mailbox. + * \param voicemail folder to look in. + * \param message number in the voicemailbox to playback to the channel. + * + * \retval 0 success + * \retval -1 failure + */ +int ast_vm_msg_play(struct ast_channel *chan, + const char *mailbox, + const char *context, + const char *folder, + const char *msg_id, + ast_vm_msg_play_cb cb); + +/*! + * \brief Get the name of a folder given its numeric index + * + * \param index The integer value of the mailbox. + * \retval "" Invalid index provided + * \retval other The name of the mailbox + */ +const char *ast_vm_index_to_foldername(unsigned int index); + +#ifdef TEST_FRAMEWORK +/*! + * \brief Add a user to the voicemail system for test purposes + * \param context The context of the mailbox + * \param mailbox The mailbox for the user + * \retval 0 success + * \retval other failure + */ +int ast_vm_test_create_user(const char *context, const char *mailbox); + +/*! + * \brief Dispose of a user. This should be used to destroy a user that was + * previously created using ast_vm_test_create_user + * \param context The context of the mailbox + * \param mailbox The mailbox for the user to destroy + */ +int ast_vm_test_destroy_user(const char *context, const char *mailbox); + +#endif + +#endif diff --git a/include/asterisk/callerid.h b/include/asterisk/callerid.h index c047632b9..7c4905e13 100644 --- a/include/asterisk/callerid.h +++ b/include/asterisk/callerid.h @@ -400,6 +400,7 @@ enum AST_REDIRECTING_REASON { AST_REDIRECTING_REASON_OUT_OF_ORDER, AST_REDIRECTING_REASON_AWAY, AST_REDIRECTING_REASON_CALL_FWD_DTE, /* This is something defined in Q.931, and no I don't know what it means */ + AST_REDIRECTING_REASON_SEND_TO_VM, }; /*! diff --git a/include/asterisk/config.h b/include/asterisk/config.h index 5e71d80b1..b2ffcf5c4 100644 --- a/include/asterisk/config.h +++ b/include/asterisk/config.h @@ -589,6 +589,63 @@ int ast_config_text_file_save(const char *filename, const struct ast_config *cfg int config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator) __attribute__((deprecated)); struct ast_config *ast_config_internal_load(const char *configfile, struct ast_config *cfg, struct ast_flags flags, const char *suggested_incl_file, const char *who_asked); +/*! + * \brief + * Copies the contents of one ast_config into another + * + * \note + * This creates a config on the heap. The caller of this must + * be prepared to free the memory returned. + * + * \param orig the config to copy + * \return The new config on success, NULL on failure. + */ +struct ast_config *ast_config_copy(const struct ast_config *orig); + +/*! + * \brief + * Flags that affect the behaviour of config hooks. + */ +enum config_hook_flags { + butt, +}; + +/* + * \brief Callback when configuration is updated + * + * \param cfg A copy of the configuration that is being changed. + * This MUST be freed by the callback before returning. + */ +typedef int (*config_hook_cb)(struct ast_config *cfg); + +/*! + * \brief + * Register a config hook for a particular file and module + * + * \param name The name of the hook you are registering. + * \param filename The file whose config you wish to hook into. + * \param module The module that is reloading the config. This + * can be useful if multiple modules may possibly + * reload the same file, but you are only interested + * when a specific module reloads the file + * \param flags Flags that affect the way hooks work. + * \param hook The callback to be called when config is loaded. + * return 0 Success + * return -1 Unsuccess, also known as UTTER AND COMPLETE FAILURE + */ +int ast_config_hook_register(const char *name, + const char *filename, + const char *module, + enum config_hook_flags flags, + config_hook_cb hook); + +/*! + * \brief + * Unregister a config hook + * + * \param name The name of the hook to unregister + */ +void ast_config_hook_unregister(const char *name); /*! * \brief Support code to parse config file arguments diff --git a/include/asterisk/event_defs.h b/include/asterisk/event_defs.h index 4d1892256..b2bf0e4ca 100644 --- a/include/asterisk/event_defs.h +++ b/include/asterisk/event_defs.h @@ -54,8 +54,10 @@ enum ast_event_type { AST_EVENT_SECURITY = 0x08, /*! Used by res_stun_monitor to alert listeners to an exernal network address change. */ AST_EVENT_NETWORK_CHANGE = 0x09, + /*! The presence state for a presence provider */ + AST_EVENT_PRESENCE_STATE = 0x0a, /*! Number of event types. This should be the last event type + 1 */ - AST_EVENT_TOTAL = 0x0a, + AST_EVENT_TOTAL = 0x0b, }; /*! \brief Event Information Element types */ @@ -287,9 +289,13 @@ enum ast_event_ie_type { AST_EVENT_IE_RECEIVED_HASH = 0x0036, AST_EVENT_IE_USING_PASSWORD = 0x0037, AST_EVENT_IE_ATTEMPTED_TRANSPORT = 0x0038, + AST_EVENT_IE_PRESENCE_PROVIDER = 0x0039, + AST_EVENT_IE_PRESENCE_STATE = 0x003a, + AST_EVENT_IE_PRESENCE_SUBTYPE = 0x003b, + AST_EVENT_IE_PRESENCE_MESSAGE = 0x003c, /*! \brief Must be the last IE value +1 */ - AST_EVENT_IE_TOTAL = 0x0039, + AST_EVENT_IE_TOTAL = 0x003d, }; /*! diff --git a/include/asterisk/file.h b/include/asterisk/file.h index e7817b377..ec2a38e1f 100644 --- a/include/asterisk/file.h +++ b/include/asterisk/file.h @@ -49,7 +49,21 @@ struct ast_format; #define AST_DIGIT_ANYNUM "0123456789" #define SEEK_FORCECUR 10 - + +/*! The type of event associated with a ast_waitstream_fr_cb invocation */ +enum ast_waitstream_fr_cb_values { + AST_WAITSTREAM_CB_REWIND = 1, + AST_WAITSTREAM_CB_FASTFORWARD, + AST_WAITSTREAM_CB_START +}; + +/*! + * \brief callback used during dtmf controlled file playback to indicate + * location of playback in a file after rewinding or fastfowarding + * a file. + */ +typedef void (ast_waitstream_fr_cb)(struct ast_channel *chan, long ms, enum ast_waitstream_fr_cb_values val); + /*! * \brief Streams a file * \param c channel to stream the file to @@ -162,6 +176,28 @@ int ast_waitstream_exten(struct ast_channel *c, const char *context); */ int ast_waitstream_fr(struct ast_channel *c, const char *breakon, const char *forward, const char *rewind, int ms); +/*! + * \brief Same as waitstream_fr but allows a callback to be alerted when a user + * fastforwards or rewinds the file. + * \param c channel to waitstream on + * \param breakon string of DTMF digits to break upon + * \param forward DTMF digit to fast forward upon + * \param rewind DTMF digit to rewind upon + * \param ms How many milliseconds to skip forward/back + * \param cb to call when rewind or fastfoward occurs. + * Begins playback of a stream... + * Wait for a stream to stop or for any one of a given digit to arrive, + * \retval 0 if the stream finishes. + * \retval the character if it was interrupted. + * \retval -1 on error. + */ +int ast_waitstream_fr_w_cb(struct ast_channel *c, + const char *breakon, + const char *forward, + const char *rewind, + int ms, + ast_waitstream_fr_cb cb); + /*! * Same as waitstream, but with audio output to fd and monitored fd checking. * diff --git a/include/asterisk/manager.h b/include/asterisk/manager.h index fac8c2bdf..257e939cf 100644 --- a/include/asterisk/manager.h +++ b/include/asterisk/manager.h @@ -86,6 +86,8 @@ #define EVENT_FLAG_CC (1 << 15) /* Call Completion events */ #define EVENT_FLAG_AOC (1 << 16) /* Advice Of Charge events */ #define EVENT_FLAG_TEST (1 << 17) /* Test event used to signal the Asterisk Test Suite */ +/*XXX Why shifted by 30? XXX */ +#define EVENT_FLAG_MESSAGE (1 << 30) /* MESSAGE events. */ /*@} */ /*! \brief Export manager structures */ diff --git a/include/asterisk/message.h b/include/asterisk/message.h index d989563e5..31ed0b28a 100644 --- a/include/asterisk/message.h +++ b/include/asterisk/message.h @@ -114,6 +114,11 @@ struct ast_msg *ast_msg_alloc(void); struct ast_msg *ast_msg_destroy(struct ast_msg *msg); /*! + * \brief Bump a msg's ref count + */ +struct ast_msg *ast_msg_ref(struct ast_msg *msg); + +/*! * \brief Set the 'to' URI of a message * * \retval 0 success @@ -159,7 +164,7 @@ int __attribute__((format(printf, 2, 3))) ast_msg_set_exten(struct ast_msg *msg, const char *fmt, ...); /*! - * \brief Set a variable on the message + * \brief Set a variable on the message going to the dialplan. * \note Setting a variable that already exists overwrites the existing variable value * * \param name Name of variable to set @@ -171,6 +176,18 @@ int __attribute__((format(printf, 2, 3))) int ast_msg_set_var(struct ast_msg *msg, const char *name, const char *value); /*! + * \brief Set a variable on the message being sent to a message tech directly. + * \note Setting a variable that already exists overwrites the existing variable value + * + * \param name Name of variable to set + * \param value Value of variable to set + * + * \retval 0 success + * \retval -1 failure + */ +int ast_msg_set_var_outbound(struct ast_msg *msg, const char *name, const char *value); + +/*! * \brief Get the specified variable on the message * \note The return value is valid only as long as the ast_message is valid. Hold a reference * to the message if you plan on storing the return value. Do re-set the same @@ -201,6 +218,17 @@ const char *ast_msg_get_body(const struct ast_msg *msg); int ast_msg_queue(struct ast_msg *msg); /*! + * \brief Send a msg directly to an endpoint. + * + * Regardless of the return value of this function, this funciton will take + * care of ensuring that the message object is properly destroyed when needed. + * + * \retval 0 message successfully queued to be sent out + * \retval non-zero failure, message not get sent out. + */ +int ast_msg_send(struct ast_msg *msg, const char *to, const char *from); + +/*! * \brief Opaque iterator for msg variables */ struct ast_msg_var_iterator; diff --git a/include/asterisk/pbx.h b/include/asterisk/pbx.h index f7dc7b919..2305f3910 100644 --- a/include/asterisk/pbx.h +++ b/include/asterisk/pbx.h @@ -26,6 +26,7 @@ #include "asterisk/channel.h" #include "asterisk/sched.h" #include "asterisk/devicestate.h" +#include "asterisk/presencestate.h" #include "asterisk/chanvars.h" #include "asterisk/hashtab.h" #include "asterisk/stringfields.h" @@ -74,9 +75,24 @@ struct ast_exten; struct ast_include; struct ast_ignorepat; struct ast_sw; + +enum ast_state_cb_update_reason { + /*! The extension state update is a result of a device state changing on the extension. */ + AST_HINT_UPDATE_DEVICE = 1, + /*! The extension state update is a result of presence state changing on the extension. */ + AST_HINT_UPDATE_PRESENCE = 2, +}; + +struct ast_state_cb_info { + enum ast_state_cb_update_reason reason; + enum ast_extension_states exten_state; + enum ast_presence_state presence_state; + const char *presence_subtype; + const char *presence_message; +}; /*! \brief Typedef for devicestate and hint callbacks */ -typedef int (*ast_state_cb_type)(const char *context, const char *exten, enum ast_extension_states state, void *data); +typedef int (*ast_state_cb_type)(char *context, char *id, struct ast_state_cb_info *info, void *data); /*! \brief Typedef for devicestate and hint callback removal indication callback */ typedef void (*ast_state_cb_destroy_type)(int id, void *data); @@ -402,6 +418,22 @@ enum ast_extension_states ast_devstate_to_extenstate(enum ast_device_state devst int ast_extension_state(struct ast_channel *c, const char *context, const char *exten); /*! + * \brief Uses hint and presence state callback to get the presence state of an extension + * + * \param c this is not important + * \param context which context to look in + * \param exten which extension to get state + * \param[out] subtype Further information regarding the presence returned + * \param[out] message Custom message further describing current presence + * + * \note The subtype and message are dynamically allocated and must be freed by + * the caller of this function. + * + * \return returns the presence state value. + */ +int ast_hint_presence_state(struct ast_channel *c, const char *context, const char *exten, char **subtype, char **message); + +/*! * \brief Return string representation of the state of an extension * * \param extension_state is the numerical state delivered by ast_extension_state diff --git a/include/asterisk/presencestate.h b/include/asterisk/presencestate.h new file mode 100644 index 000000000..dbbe5dcab --- /dev/null +++ b/include/asterisk/presencestate.h @@ -0,0 +1,154 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 2011, Digium, Inc. + * + * David Vossel <dvossel@digium.com> + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ + +/*! \file + * \brief Presence state management + */ + +#ifndef _ASTERISK_PRESSTATE_H +#define _ASTERISK_PRESSTATE_H + +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, + /* 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, +}; + +/*! \brief Presence state provider call back */ +typedef enum ast_presence_state (*ast_presence_state_prov_cb_type)(const char *data, char **subtype, char **message); + +/*! + * \brief Convert presence state to text string for output + * + * \param state Current presence state + */ +const char *ast_presence_state2str(enum ast_presence_state state); + +/*! + * \brief Convert presence state from text to integer value + * + * \param val The text representing the presence state. Valid values are anything + * that comes after AST_PRESENCE_ in one of the defined values. + * + * \return The AST_PRESENCE_ integer value + */ +enum ast_presence_state ast_presence_state_val(const char *val); + +/*! + * \brief Asks a presence state provider for the current presence state. + * + * \param presence_provider, The presence provider to retrieve the state from. + * \param subtype, The output paramenter to store the subtype string in. Must be freed if returned + * \param message, The output paramenter to store the message string in. Must be freed if returned + * + * \retval presence state value on success, + * \retval -1 on failure. + */ +enum ast_presence_state ast_presence_state(const char *presence_provider, char **subtype, char **message); + +/*! + * \brief Asks a presence state provider for the current presence state, bypassing the event cache + * + * \details 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. + * + * \param presence_provider, The presence provider to retrieve the state from. + * \param subtype, The output paramenter to store the subtype string in. Must be freed if returned + * \param message, The output paramenter to store the message string in. Must be freed if returned + * + * \retval presence state value on success, + * \retval -1 on failure. + */ +enum ast_presence_state ast_presence_state_nocache(const char *presence_provider, char **subtype, char **message); + +/*! + * \brief Notify the world that a presence provider state changed. + * + * \param state the new presence state + * \param subtype the new presence subtype + * \param message the new presence message + * \param 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. + * + * \retval 0 Success + * \retval -1 Failure + */ +int ast_presence_state_changed(enum ast_presence_state state, + const char *subtype, + const char *message, + const char *fmt, ...) + __attribute__((format(printf, 4, 5))); + +/*! + * \brief Notify the world that a presence provider state changed. + * + * \param state the new presence state + * \param subtype the new presence subtype + * \param message the new presence message + * \param 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. + * + * \retval 0 Success + * \retval -1 Failure + */ +int ast_presence_state_changed_literal(enum ast_presence_state state, + const char *subtype, + const char *message, + const char *presence_provider); + +/*! + * \brief Add presence state provider + * + * \param label to use in hint, like label:object + * \param callback Callback + * + * \retval 0 success + * \retval -1 failure + */ +int ast_presence_state_prov_add(const char *label, ast_presence_state_prov_cb_type callback); + +/*! + * \brief Remove presence state provider + * + * \param label to use in hint, like label:object + * + * \retval -1 on failure + * \retval 0 on success + */ +int ast_presence_state_prov_del(const char *label); + +int ast_presence_state_engine_init(void); +#endif + diff --git a/include/asterisk/sip_api.h b/include/asterisk/sip_api.h new file mode 100644 index 000000000..018785a8d --- /dev/null +++ b/include/asterisk/sip_api.h @@ -0,0 +1,51 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 2012, Digium, Inc. + * + * Mark Michelson <mmichelson@digium.com> + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ + +#ifndef __ASTERISK_SIP_H +#define __ASTERISK_SIP_H + +#if defined(__cplusplus) || defined(c_plusplus) +extern "C" { +#endif + +#include "asterisk/optional_api.h" +#include "asterisk/config.h" + +/*! + * \brief Send a customized SIP INFO request + * + * \param headers The headers to add to the INFO request + * \param content_type The content type header to add + * \param conten The body of the INFO request + * \param useragent_filter If non-NULL, only send the INFO if the + * recipient's User-Agent contains useragent_filter as a substring + * + * \retval 0 Success + * \retval non-zero Failure + */ +int ast_sipinfo_send(struct ast_channel *chan, + struct ast_variable *headers, + const char *content_type, + const char *content, + const char *useragent_filter); + +#if defined(__cplusplus) || defined(c_plusplus) +} +#endif + +#endif /* __ASTERISK_SIP_H */ |