326 lines
8.8 KiB
C
326 lines
8.8 KiB
C
/*
|
|
* Asterisk -- An open source telephony toolkit.
|
|
*
|
|
* Copyright (C) 2023, Commend International
|
|
*
|
|
* Maximilian Fridrich <m.fridrich@commend.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 Out-of-call refer support
|
|
*
|
|
* \author Maximilian Fridrich <m.fridrich@commend.com>
|
|
*
|
|
* The purpose of this API is to provide support for refers that
|
|
* are not session based. The refers are passed into the Asterisk core
|
|
* to be routed through the dialplan or another interface and potentially
|
|
* sent back out through a refer technology that has been registered
|
|
* through this API.
|
|
*/
|
|
|
|
#ifndef __AST_REFER_H__
|
|
#define __AST_REFER_H__
|
|
|
|
#if defined(__cplusplus) || defined(c_plusplus)
|
|
extern "C" {
|
|
#endif
|
|
|
|
/*!
|
|
* \brief A refer structure.
|
|
*
|
|
* This is an opaque type that represents a refer.
|
|
*/
|
|
struct ast_refer;
|
|
|
|
/*!
|
|
* \brief A refer technology
|
|
*
|
|
* A refer technology is capable of transmitting text refers.
|
|
*/
|
|
struct ast_refer_tech {
|
|
/*!
|
|
* \brief Name of this refer technology
|
|
*
|
|
* This is the name that comes at the beginning of a URI for refers
|
|
* that should be sent to this refer technology implementation.
|
|
* For example, refers sent to "pjsip:m.fridrich@commend.com" would be
|
|
* passed to the ast_refer_tech with a name of "pjsip".
|
|
*/
|
|
const char * const name;
|
|
/*!
|
|
* \brief Send a refer.
|
|
*
|
|
* \param refer The refer to send
|
|
*
|
|
* The fields of the ast_refer are guaranteed not to change during the
|
|
* duration of this function call.
|
|
*
|
|
* \retval 0 success
|
|
* \retval non-zero failure
|
|
*/
|
|
int (* const refer_send)(const struct ast_refer *refer);
|
|
};
|
|
|
|
/*!
|
|
* \brief Register a refer technology
|
|
*
|
|
* \retval 0 success
|
|
* \retval non-zero failure
|
|
*/
|
|
int ast_refer_tech_register(const struct ast_refer_tech *tech);
|
|
|
|
/*!
|
|
* \brief Unregister a refer technology.
|
|
*
|
|
* \retval 0 success
|
|
* \retval non-zero failure
|
|
*/
|
|
int ast_refer_tech_unregister(const struct ast_refer_tech *tech);
|
|
|
|
/*!
|
|
* \brief Allocate a refer.
|
|
*
|
|
* Allocate a refer for the purposes of passing it into the Asterisk core
|
|
* to be routed through the dialplan. This refer must be destroyed using
|
|
* ast_refer_destroy().
|
|
*
|
|
* \return A refer object. This function will return NULL if an allocation
|
|
* error occurs.
|
|
*/
|
|
struct ast_refer *ast_refer_alloc(void);
|
|
|
|
/*!
|
|
* \brief Destroy an ast_refer
|
|
*
|
|
* \retval NULL always.
|
|
*/
|
|
struct ast_refer *ast_refer_destroy(struct ast_refer *refer);
|
|
|
|
/*!
|
|
* \brief Bump a refer's ref count
|
|
*/
|
|
struct ast_refer *ast_refer_ref(struct ast_refer *refer);
|
|
|
|
/*!
|
|
* \brief Set the 'to' URI of a refer
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*/
|
|
int __attribute__((format(printf, 2, 3)))
|
|
ast_refer_set_to(struct ast_refer *refer, const char *fmt, ...);
|
|
|
|
/*!
|
|
* \brief Set the 'from' URI of a refer
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*/
|
|
int __attribute__((format(printf, 2, 3)))
|
|
ast_refer_set_from(struct ast_refer *refer, const char *fmt, ...);
|
|
|
|
/*!
|
|
* \brief Set the 'refer_to' URI of a refer
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*/
|
|
int __attribute__((format(printf, 2, 3)))
|
|
ast_refer_set_refer_to(struct ast_refer *refer, const char *fmt, ...);
|
|
|
|
/*!
|
|
* \brief Set the 'to_self' value of a refer
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*/
|
|
int ast_refer_set_to_self(struct ast_refer *refer, int val);
|
|
|
|
/*!
|
|
* \brief Set the technology associated with this refer
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*/
|
|
int __attribute__((format(printf, 2, 3)))
|
|
ast_refer_set_tech(struct ast_refer *refer, const char *fmt, ...);
|
|
|
|
/*!
|
|
* \brief Set the technology's endpoint associated with this refer
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*/
|
|
int __attribute__((format(printf, 2, 3)))
|
|
ast_refer_set_endpoint(struct ast_refer *refer, const char *fmt, ...);
|
|
|
|
/*!
|
|
* \brief Set a variable on the refer being sent to a refer tech directly.
|
|
* \note Setting a variable that already exists overwrites the existing variable value
|
|
*
|
|
* \param refer
|
|
* \param name Name of variable to set
|
|
* \param value Value of variable to set
|
|
*
|
|
* \retval 0 success
|
|
* \retval -1 failure
|
|
*/
|
|
int ast_refer_set_var_outbound(struct ast_refer *refer, const char *name, const char *value);
|
|
|
|
/*!
|
|
* \brief Get the specified variable on the refer and unlink it from the container of variables
|
|
* \note The return value must be freed by the caller.
|
|
*
|
|
* \param refer
|
|
* \param name Name of variable to get
|
|
*
|
|
* \return The value associated with variable "name". NULL if variable not found.
|
|
*/
|
|
char *ast_refer_get_var_and_unlink(struct ast_refer *refer, const char *name);
|
|
|
|
/*!
|
|
* \brief Get the specified variable on the refer
|
|
* \note The return value is valid only as long as the ast_refer is valid. Hold a reference
|
|
* to the refer if you plan on storing the return value. It is possible to re-set the
|
|
* same refer var name (with ast_refer_set_var_outbound passing the variable name)
|
|
* while holding a pointer to the result of this function.
|
|
*
|
|
* \param refer
|
|
* \param name Name of variable to get
|
|
*
|
|
* \return The value associated with variable "name". NULL if variable not found.
|
|
*/
|
|
const char *ast_refer_get_var(struct ast_refer *refer, const char *name);
|
|
|
|
/*!
|
|
* \brief Get the "refer-to" value of a refer.
|
|
* \note The return value is valid only as long as the ast_refer is valid. Hold a reference
|
|
* to the refer if you plan on storing the return value.
|
|
*
|
|
* \param refer The refer to get the "refer-to" value from
|
|
*
|
|
* \return The "refer-to" value of the refer, encoded in UTF-8.
|
|
*/
|
|
const char *ast_refer_get_refer_to(const struct ast_refer *refer);
|
|
|
|
/*!
|
|
* \brief Retrieve the source of this refer
|
|
*
|
|
* \param refer The refer to get the soure from
|
|
*
|
|
* \return The source of the refer
|
|
* \retval NULL or empty string if the refer has no source
|
|
*/
|
|
const char *ast_refer_get_from(const struct ast_refer *refer);
|
|
|
|
/*!
|
|
* \brief Retrieve the destination of this refer
|
|
*
|
|
* \param refer The refer to get the destination from
|
|
*
|
|
* \return The destination of the refer
|
|
* \retval NULL or empty string if the refer has no destination
|
|
*/
|
|
const char *ast_refer_get_to(const struct ast_refer *refer);
|
|
|
|
/*!
|
|
* \brief Retrieve the "to_self" value of this refer
|
|
*
|
|
* \param refer The refer to get the destination from
|
|
*
|
|
* \return The to_self value of the refer
|
|
*/
|
|
int ast_refer_get_to_self(const struct ast_refer *refer);
|
|
|
|
/*!
|
|
* \brief Retrieve the technology associated with this refer
|
|
*
|
|
* \param refer The refer to get the technology from
|
|
*
|
|
* \return The technology of the refer
|
|
* \retval NULL or empty string if the refer has no associated technology
|
|
*/
|
|
const char *ast_refer_get_tech(const struct ast_refer *refer);
|
|
|
|
/*!
|
|
* \brief Retrieve the endpoint associated with this refer
|
|
*
|
|
* \param refer The refer to get the endpoint from
|
|
*
|
|
* \return The endpoint associated with the refer
|
|
* \retval NULL or empty string if the refer has no associated endpoint
|
|
*/
|
|
const char *ast_refer_get_endpoint(const struct ast_refer *refer);
|
|
|
|
/*!
|
|
* \brief Send a refer directly to an endpoint.
|
|
*
|
|
* Regardless of the return value of this function, this function will take
|
|
* care of ensuring that the refer object is properly destroyed when needed.
|
|
*
|
|
* \retval 0 refer successfully queued to be sent out
|
|
* \retval non-zero failure, refer not get sent out.
|
|
*/
|
|
int ast_refer_send(struct ast_refer *refer);
|
|
|
|
/*!
|
|
* \brief Opaque iterator for refer variables
|
|
*/
|
|
struct ast_refer_var_iterator;
|
|
|
|
/*!
|
|
* \brief Create a new refer variable iterator
|
|
* \param refer A refer whose variables are to be iterated over
|
|
*
|
|
* \return An opaque pointer to the new iterator
|
|
*/
|
|
struct ast_refer_var_iterator *ast_refer_var_iterator_init(const struct ast_refer *refer);
|
|
|
|
/*!
|
|
* \brief Get the next variable name and value
|
|
*
|
|
* \param iter An iterator created with ast_refer_var_iterator_init
|
|
* \param name A pointer to the name result pointer
|
|
* \param value A pointer to the value result pointer
|
|
*
|
|
* \note The refcount to iter->current_used must be decremented by the caller
|
|
* by calling ast_refer_var_unref_current.
|
|
*
|
|
* \retval 0 No more entries
|
|
* \retval 1 Valid entry
|
|
*/
|
|
int ast_refer_var_iterator_next(struct ast_refer_var_iterator *iter, const char **name, const char **value);
|
|
|
|
/*!
|
|
* \brief Destroy a refer variable iterator
|
|
* \param iter Iterator to be destroyed
|
|
*/
|
|
void ast_refer_var_iterator_destroy(struct ast_refer_var_iterator *iter);
|
|
|
|
/*!
|
|
* \brief Unref a refer var from inside an iterator loop
|
|
*/
|
|
void ast_refer_var_unref_current(struct ast_refer_var_iterator *iter);
|
|
|
|
/*!
|
|
* @}
|
|
*/
|
|
|
|
#if defined(__cplusplus) || defined(c_plusplus)
|
|
}
|
|
#endif
|
|
|
|
#endif /* __AST_REFER_H__ */
|