diff options
author | Benny Prijono <bennylp@teluu.com> | 2005-11-21 01:55:47 +0000 |
---|---|---|
committer | Benny Prijono <bennylp@teluu.com> | 2005-11-21 01:55:47 +0000 |
commit | 5f1de1bbb341ea1dc1d27d9bf35764b643ef904a (patch) | |
tree | d18b0365b69b8b488a0b2b2bd715e9f14f77b505 /pjsip/include | |
parent | 9f4da35e676737f830a90a18de08440cf0f6cdf9 (diff) |
Set svn:eol-style property
git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@65 74dad513-b988-da41-8d7b-12977e46ad98
Diffstat (limited to 'pjsip/include')
29 files changed, 7913 insertions, 7884 deletions
diff --git a/pjsip/include/pjsip-simple/event_notify.h b/pjsip/include/pjsip-simple/event_notify.h index 15561505..5f002582 100644 --- a/pjsip/include/pjsip-simple/event_notify.h +++ b/pjsip/include/pjsip-simple/event_notify.h @@ -1,330 +1,330 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIMPLE_EVENT_NOTIFY_H__
-#define __PJSIP_SIMPLE_EVENT_NOTIFY_H__
-
-/**
- * @file event_notify.h
- * @brief SIP Specific Event Notification Extension (RFC 3265)
- */
-
-#include <pjsip/sip_types.h>
-#include <pjsip/sip_auth.h>
-#include <pjsip_simple/event_notify_msg.h>
-#include <pj/timer.h>
-
-/**
- * @defgroup PJSIP_EVENT_NOT SIP Event Notification (RFC 3265) Module
- * @ingroup PJSIP_SIMPLE
- * @{
- *
- * This module provides the implementation of SIP Extension for SIP Specific
- * Event Notification (RFC 3265). It extends PJSIP by supporting SUBSCRIBE and
- * NOTIFY methods.
- *
- * This module itself is extensible; new event packages can be registered to
- * this module to handle specific extensions (such as presence).
- */
-
-PJ_BEGIN_DECL
-
-typedef struct pjsip_event_sub_cb pjsip_event_sub_cb;
-typedef struct pjsip_event_sub pjsip_event_sub;
-
-/**
- * This enumeration describes subscription state as described in the RFC 3265.
- * The standard specifies that extensions may define additional states. In the
- * case where the state is not known, the subscription state will be set to
- * PJSIP_EVENT_SUB_STATE_UNKNOWN, and the token will be kept in state_str
- * member of the susbcription structure.
- */
-typedef enum pjsip_event_sub_state
-{
- /** State is NULL. */
- PJSIP_EVENT_SUB_STATE_NULL,
-
- /** Subscription is active. */
- PJSIP_EVENT_SUB_STATE_ACTIVE,
-
- /** Subscription is pending. */
- PJSIP_EVENT_SUB_STATE_PENDING,
-
- /** Subscription is terminated. */
- PJSIP_EVENT_SUB_STATE_TERMINATED,
-
- /** Subscription state can not be determined. Application can query
- * the state information in state_str member.
- */
- PJSIP_EVENT_SUB_STATE_UNKNOWN,
-
-} pjsip_event_sub_state;
-
-/**
- * This structure describes notification to be called when incoming SUBSCRIBE
- * request is received. The module will call the callback registered by package
- * that matches the event description in the incoming SUBSCRIBE.
- */
-typedef struct pjsip_event_sub_pkg_cb
-{
- /**
- * This callback is called to first enquery the package whether it wants
- * to accept incoming SUBSCRIBE request. If it does, then on_subscribe
- * will be called.
- *
- * @param rdata The incoming request.
- * @param status The status code to be returned back to subscriber.
- */
- void (*on_query_subscribe)(pjsip_rx_data *rdata, int *status);
-
- /**
- * This callback is called when the module receives incoming SUBSCRIBE
- * request.
- *
- * @param sub The subscription instance.
- * @param rdata The received buffer.
- * @param cb Callback to be registered to the subscription instance.
- * @param expires The expiration to be set.
- */
- void (*on_subscribe)(pjsip_event_sub *sub, pjsip_rx_data *rdata,
- pjsip_event_sub_cb **cb, int *expires);
-
-} pjsip_event_sub_pkg_cb;
-
-/**
- * This structure describes callback that is registered by application or
- * package to receive notifications about a subscription.
- */
-struct pjsip_event_sub_cb
-{
- /**
- * This callback is used by both subscriber and notifier. It is called
- * when the subscription has been terminated.
- *
- * @param sub The subscription instance.
- * @param reason The termination reason.
- */
- void (*on_sub_terminated)(pjsip_event_sub *sub, const pj_str_t *reason);
-
- /**
- * This callback is called when we received SUBSCRIBE request to refresh
- * the subscription.
- *
- * @param sub The subscription instance.
- * @param rdata The received SUBSCRIBE request.
- */
- void (*on_received_refresh)(pjsip_event_sub *sub, pjsip_rx_data *rdata);
-
- /**
- * This callback is called when the module receives final response on
- * previously sent SUBSCRIBE request.
- *
- * @param sub The subscription instance.
- * @param event The event.
- */
- void (*on_received_sub_response)(pjsip_event_sub *sub, pjsip_event *event);
-
- /**
- * This callback is called when the module receives incoming NOTIFY
- * request.
- *
- * @param sub The subscription instance.
- * @param rdata The received data.
- */
- void (*on_received_notify)(pjsip_event_sub *sub, pjsip_rx_data *rdata);
-
- /**
- * This callback is called when the module receives final response to
- * previously sent NOTIFY request.
- *
- * @param sub The subscription instance.
- * @param event The event.
- */
- void (*on_received_notify_response)(pjsip_event_sub *sub, pjsip_event *event);
-
-};
-
-/**
- * This structure describes an event subscription record. The structure is used
- * to represent both subscriber and notifier.
- */
-struct pjsip_event_sub
-{
- pj_pool_t *pool; /**< Pool. */
- pjsip_endpoint *endpt; /**< Endpoint. */
- pjsip_event_sub_cb cb; /**< Callback. */
- pj_mutex_t *mutex; /**< Mutex. */
- pjsip_role_e role; /**< Role (UAC=subscriber, UAS=notifier) */
- pjsip_event_sub_state state; /**< Subscription state. */
- pj_str_t state_str; /**< String describing the state. */
- pjsip_from_hdr *from; /**< Cached local info (From) */
- pjsip_to_hdr *to; /**< Cached remote info (To) */
- pjsip_contact_hdr *contact; /**< Cached local contact. */
- pjsip_cid_hdr *call_id; /**< Cached Call-ID */
- int cseq; /**< Outgoing CSeq */
- pjsip_event_hdr *event; /**< Event description. */
- pjsip_expires_hdr *uac_expires; /**< Cached Expires header (UAC only). */
- pjsip_accept_hdr *local_accept; /**< Local Accept header. */
- pjsip_route_hdr route_set; /**< Route-set. */
-
- pj_str_t key; /**< Key in the hash table. */
- void *user_data; /**< Application data. */
- int default_interval; /**< Refresh interval. */
- pj_timer_entry timer; /**< Internal timer. */
- pj_time_val expiry_time; /**< Time when subscription expires. */
- int pending_tsx; /**< Number of pending transactions. */
- pj_bool_t delete_flag; /**< Pending deletion flag. */
-
- pjsip_auth_session auth_sess; /**< Authorization sessions. */
- unsigned cred_cnt; /**< Number of credentials. */
- pjsip_cred_info *cred_info; /**< Array of credentials. */
-};
-
-
-
-
-/**
- * Initialize the module and get the instance of the module to be registered to
- * endpoint.
- *
- * @return The module instance.
- */
-PJ_DECL(pjsip_module*) pjsip_event_sub_get_module(void);
-
-
-/**
- * Register event package.
- *
- * @param event The event identification for the package.
- * @param accept_cnt Number of strings in Accept array.
- * @param accept Array of Accept value.
- * @param cb Callback to receive incoming SUBSCRIBE for the package.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_event_sub_register_pkg( const pj_str_t *event_name,
- int accept_cnt,
- const pj_str_t accept[],
- const pjsip_event_sub_pkg_cb *cb );
-
-
-/**
- * Create initial subscription instance (client).
- *
- * @param endpt The endpoint.
- * @param from URL to put in From header.
- * @param to The target resource.
- * @param event Event package.
- * @param expires Expiration time.
- * @param accept Accept specification.
- * @param user_data Application data to attach to this subscription.
- *
- * @return New client subscription instance.
- */
-PJ_DECL(pjsip_event_sub*) pjsip_event_sub_create( pjsip_endpoint *endpt,
- const pj_str_t *from,
- const pj_str_t *to,
- const pj_str_t *event,
- int expires,
- int accept_cnt,
- const pj_str_t accept[],
- void *user_data,
- const pjsip_event_sub_cb *cb);
-
-/**
- * Set credentials to be used for outgoing request messages.
- *
- * @param sub Subscription instance.
- * @param count Number of credentials.
- * @param cred Array of credential info.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_event_sub_set_credentials( pjsip_event_sub *sub,
- int count,
- const pjsip_cred_info cred[]);
-
-/**
- * Set route set for outgoing requests.
- *
- * @param sub Subscription instance.
- * @param route_set List of route headers.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_event_sub_set_route_set( pjsip_event_sub *sub,
- const pjsip_route_hdr *route_set );
-
-
-/**
- * Send SUBSCRIBE request.
- *
- * @param sub Subscription instance.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_event_sub_subscribe( pjsip_event_sub *sub );
-
-/**
- * Terminate subscription (client). This will send unsubscription request to
- * notifier.
- *
- * @param sub Client subscription instance.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_event_sub_unsubscribe( pjsip_event_sub *sub );
-
-
-/**
- * For notifier, send NOTIFY request to subscriber, and set the state of
- * the subscription.
- *
- * @param sub The server subscription (notifier) instance.
- * @param state New state to set.
- * @param reason Specify reason if new state is terminated, otherwise
- * put NULL.
- * @param type Description of content type.
- * @param body Text body to send with the NOTIFY, or NULL if the
- * NOTIFY request should not contain any message body.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_event_sub_notify( pjsip_event_sub *sub,
- pjsip_event_sub_state state,
- const pj_str_t *reason,
- pjsip_msg_body *body);
-
-/**
- * Destroy subscription instance.
- *
- * @param sub The client or server subscription instance.
- *
- * @return Zero on success, one if the subscription will be
- * deleted automatically later, or -1 on error.
- */
-PJ_DECL(pj_status_t) pjsip_event_sub_destroy(pjsip_event_sub *sub);
-
-
-PJ_END_DECL
-
-/**
- * @}
- */
-
-#endif /* __PJSIP_SIMPLE_EVENT_NOTIFY_H__ */
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIMPLE_EVENT_NOTIFY_H__ +#define __PJSIP_SIMPLE_EVENT_NOTIFY_H__ + +/** + * @file event_notify.h + * @brief SIP Specific Event Notification Extension (RFC 3265) + */ + +#include <pjsip/sip_types.h> +#include <pjsip/sip_auth.h> +#include <pjsip_simple/event_notify_msg.h> +#include <pj/timer.h> + +/** + * @defgroup PJSIP_EVENT_NOT SIP Event Notification (RFC 3265) Module + * @ingroup PJSIP_SIMPLE + * @{ + * + * This module provides the implementation of SIP Extension for SIP Specific + * Event Notification (RFC 3265). It extends PJSIP by supporting SUBSCRIBE and + * NOTIFY methods. + * + * This module itself is extensible; new event packages can be registered to + * this module to handle specific extensions (such as presence). + */ + +PJ_BEGIN_DECL + +typedef struct pjsip_event_sub_cb pjsip_event_sub_cb; +typedef struct pjsip_event_sub pjsip_event_sub; + +/** + * This enumeration describes subscription state as described in the RFC 3265. + * The standard specifies that extensions may define additional states. In the + * case where the state is not known, the subscription state will be set to + * PJSIP_EVENT_SUB_STATE_UNKNOWN, and the token will be kept in state_str + * member of the susbcription structure. + */ +typedef enum pjsip_event_sub_state +{ + /** State is NULL. */ + PJSIP_EVENT_SUB_STATE_NULL, + + /** Subscription is active. */ + PJSIP_EVENT_SUB_STATE_ACTIVE, + + /** Subscription is pending. */ + PJSIP_EVENT_SUB_STATE_PENDING, + + /** Subscription is terminated. */ + PJSIP_EVENT_SUB_STATE_TERMINATED, + + /** Subscription state can not be determined. Application can query + * the state information in state_str member. + */ + PJSIP_EVENT_SUB_STATE_UNKNOWN, + +} pjsip_event_sub_state; + +/** + * This structure describes notification to be called when incoming SUBSCRIBE + * request is received. The module will call the callback registered by package + * that matches the event description in the incoming SUBSCRIBE. + */ +typedef struct pjsip_event_sub_pkg_cb +{ + /** + * This callback is called to first enquery the package whether it wants + * to accept incoming SUBSCRIBE request. If it does, then on_subscribe + * will be called. + * + * @param rdata The incoming request. + * @param status The status code to be returned back to subscriber. + */ + void (*on_query_subscribe)(pjsip_rx_data *rdata, int *status); + + /** + * This callback is called when the module receives incoming SUBSCRIBE + * request. + * + * @param sub The subscription instance. + * @param rdata The received buffer. + * @param cb Callback to be registered to the subscription instance. + * @param expires The expiration to be set. + */ + void (*on_subscribe)(pjsip_event_sub *sub, pjsip_rx_data *rdata, + pjsip_event_sub_cb **cb, int *expires); + +} pjsip_event_sub_pkg_cb; + +/** + * This structure describes callback that is registered by application or + * package to receive notifications about a subscription. + */ +struct pjsip_event_sub_cb +{ + /** + * This callback is used by both subscriber and notifier. It is called + * when the subscription has been terminated. + * + * @param sub The subscription instance. + * @param reason The termination reason. + */ + void (*on_sub_terminated)(pjsip_event_sub *sub, const pj_str_t *reason); + + /** + * This callback is called when we received SUBSCRIBE request to refresh + * the subscription. + * + * @param sub The subscription instance. + * @param rdata The received SUBSCRIBE request. + */ + void (*on_received_refresh)(pjsip_event_sub *sub, pjsip_rx_data *rdata); + + /** + * This callback is called when the module receives final response on + * previously sent SUBSCRIBE request. + * + * @param sub The subscription instance. + * @param event The event. + */ + void (*on_received_sub_response)(pjsip_event_sub *sub, pjsip_event *event); + + /** + * This callback is called when the module receives incoming NOTIFY + * request. + * + * @param sub The subscription instance. + * @param rdata The received data. + */ + void (*on_received_notify)(pjsip_event_sub *sub, pjsip_rx_data *rdata); + + /** + * This callback is called when the module receives final response to + * previously sent NOTIFY request. + * + * @param sub The subscription instance. + * @param event The event. + */ + void (*on_received_notify_response)(pjsip_event_sub *sub, pjsip_event *event); + +}; + +/** + * This structure describes an event subscription record. The structure is used + * to represent both subscriber and notifier. + */ +struct pjsip_event_sub +{ + pj_pool_t *pool; /**< Pool. */ + pjsip_endpoint *endpt; /**< Endpoint. */ + pjsip_event_sub_cb cb; /**< Callback. */ + pj_mutex_t *mutex; /**< Mutex. */ + pjsip_role_e role; /**< Role (UAC=subscriber, UAS=notifier) */ + pjsip_event_sub_state state; /**< Subscription state. */ + pj_str_t state_str; /**< String describing the state. */ + pjsip_from_hdr *from; /**< Cached local info (From) */ + pjsip_to_hdr *to; /**< Cached remote info (To) */ + pjsip_contact_hdr *contact; /**< Cached local contact. */ + pjsip_cid_hdr *call_id; /**< Cached Call-ID */ + int cseq; /**< Outgoing CSeq */ + pjsip_event_hdr *event; /**< Event description. */ + pjsip_expires_hdr *uac_expires; /**< Cached Expires header (UAC only). */ + pjsip_accept_hdr *local_accept; /**< Local Accept header. */ + pjsip_route_hdr route_set; /**< Route-set. */ + + pj_str_t key; /**< Key in the hash table. */ + void *user_data; /**< Application data. */ + int default_interval; /**< Refresh interval. */ + pj_timer_entry timer; /**< Internal timer. */ + pj_time_val expiry_time; /**< Time when subscription expires. */ + int pending_tsx; /**< Number of pending transactions. */ + pj_bool_t delete_flag; /**< Pending deletion flag. */ + + pjsip_auth_session auth_sess; /**< Authorization sessions. */ + unsigned cred_cnt; /**< Number of credentials. */ + pjsip_cred_info *cred_info; /**< Array of credentials. */ +}; + + + + +/** + * Initialize the module and get the instance of the module to be registered to + * endpoint. + * + * @return The module instance. + */ +PJ_DECL(pjsip_module*) pjsip_event_sub_get_module(void); + + +/** + * Register event package. + * + * @param event The event identification for the package. + * @param accept_cnt Number of strings in Accept array. + * @param accept Array of Accept value. + * @param cb Callback to receive incoming SUBSCRIBE for the package. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_event_sub_register_pkg( const pj_str_t *event_name, + int accept_cnt, + const pj_str_t accept[], + const pjsip_event_sub_pkg_cb *cb ); + + +/** + * Create initial subscription instance (client). + * + * @param endpt The endpoint. + * @param from URL to put in From header. + * @param to The target resource. + * @param event Event package. + * @param expires Expiration time. + * @param accept Accept specification. + * @param user_data Application data to attach to this subscription. + * + * @return New client subscription instance. + */ +PJ_DECL(pjsip_event_sub*) pjsip_event_sub_create( pjsip_endpoint *endpt, + const pj_str_t *from, + const pj_str_t *to, + const pj_str_t *event, + int expires, + int accept_cnt, + const pj_str_t accept[], + void *user_data, + const pjsip_event_sub_cb *cb); + +/** + * Set credentials to be used for outgoing request messages. + * + * @param sub Subscription instance. + * @param count Number of credentials. + * @param cred Array of credential info. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_event_sub_set_credentials( pjsip_event_sub *sub, + int count, + const pjsip_cred_info cred[]); + +/** + * Set route set for outgoing requests. + * + * @param sub Subscription instance. + * @param route_set List of route headers. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_event_sub_set_route_set( pjsip_event_sub *sub, + const pjsip_route_hdr *route_set ); + + +/** + * Send SUBSCRIBE request. + * + * @param sub Subscription instance. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_event_sub_subscribe( pjsip_event_sub *sub ); + +/** + * Terminate subscription (client). This will send unsubscription request to + * notifier. + * + * @param sub Client subscription instance. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_event_sub_unsubscribe( pjsip_event_sub *sub ); + + +/** + * For notifier, send NOTIFY request to subscriber, and set the state of + * the subscription. + * + * @param sub The server subscription (notifier) instance. + * @param state New state to set. + * @param reason Specify reason if new state is terminated, otherwise + * put NULL. + * @param type Description of content type. + * @param body Text body to send with the NOTIFY, or NULL if the + * NOTIFY request should not contain any message body. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_event_sub_notify( pjsip_event_sub *sub, + pjsip_event_sub_state state, + const pj_str_t *reason, + pjsip_msg_body *body); + +/** + * Destroy subscription instance. + * + * @param sub The client or server subscription instance. + * + * @return Zero on success, one if the subscription will be + * deleted automatically later, or -1 on error. + */ +PJ_DECL(pj_status_t) pjsip_event_sub_destroy(pjsip_event_sub *sub); + + +PJ_END_DECL + +/** + * @} + */ + +#endif /* __PJSIP_SIMPLE_EVENT_NOTIFY_H__ */ diff --git a/pjsip/include/pjsip-simple/event_notify_msg.h b/pjsip/include/pjsip-simple/event_notify_msg.h index 95f5a48a..76b7d35c 100644 --- a/pjsip/include/pjsip-simple/event_notify_msg.h +++ b/pjsip/include/pjsip-simple/event_notify_msg.h @@ -1,117 +1,117 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIMPLE_EVENT_NOTIFY_MSG_H__
-#define __PJSIP_SIMPLE_EVENT_NOTIFY_MSG_H__
-
-/**
- * @file event_notify_msg.h
- * @brief SIP Event Notification Headers (RFC 3265)
- */
-#include <pjsip/sip_msg.h>
-
-/**
- * @ingroup PJSIP_EVENT_NOT
- * @{
- */
-
-PJ_BEGIN_DECL
-
-
-/** Max events in Allow-Events header. */
-#define PJSIP_MAX_ALLOW_EVENTS 16
-
-/**
- * This structure describes Event header.
- */
-typedef struct pjsip_event_hdr
-{
- PJSIP_DECL_HDR_MEMBER(struct pjsip_event_hdr)
- pj_str_t event_type; /**< Event name. */
- pj_str_t id_param; /**< Optional event ID parameter. */
- pj_str_t other_param; /**< Other parameter, concatenated together. */
-} pjsip_event_hdr;
-
-/**
- * Create an Event header.
- *
- * @param pool The pool.
- *
- * @return New Event header instance.
- */
-PJ_DECL(pjsip_event_hdr*) pjsip_event_hdr_create(pj_pool_t *pool);
-
-
-/**
- * This structure describes Allow-Events header.
- */
-typedef struct pjsip_allow_events_hdr
-{
- PJSIP_DECL_HDR_MEMBER(struct pjsip_allow_events_hdr)
- int event_cnt; /**< Number of event names. */
- pj_str_t events[PJSIP_MAX_ALLOW_EVENTS]; /**< Event names. */
-} pjsip_allow_events_hdr;
-
-
-/**
- * Create a new Allow-Events header.
- *
- * @param pool. The pool.
- *
- * @return Allow-Events header.
- */
-PJ_DECL(pjsip_allow_events_hdr*) pjsip_allow_events_hdr_create(pj_pool_t *pool);
-
-
-/**
- * This structure describes Subscription-State header.
- */
-typedef struct pjsip_sub_state_hdr
-{
- PJSIP_DECL_HDR_MEMBER(struct pjsip_sub_state_hdr)
- pj_str_t sub_state; /**< Subscription state. */
- pj_str_t reason_param; /**< Optional termination reason. */
- int expires_param; /**< Expires param, or -1. */
- int retry_after; /**< Retry after param, or -1. */
- pj_str_t other_param; /**< Other parameter, concatenated together. */
-} pjsip_sub_state_hdr;
-
-/**
- * Create new Subscription-State header.
- *
- * @param pool The pool.
- *
- * @return Subscription-State header.
- */
-PJ_DECL(pjsip_sub_state_hdr*) pjsip_sub_state_hdr_create(pj_pool_t *pool);
-
-/**
- * Initialize parser for event notify module.
- */
-PJ_DEF(void) pjsip_event_notify_init_parser(void);
-
-
-PJ_END_DECL
-
-
-/**
- * @}
- */
-
-#endif /* __PJSIP_SIMPLE_EVENT_NOTIFY_MSG_H__ */
-
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIMPLE_EVENT_NOTIFY_MSG_H__ +#define __PJSIP_SIMPLE_EVENT_NOTIFY_MSG_H__ + +/** + * @file event_notify_msg.h + * @brief SIP Event Notification Headers (RFC 3265) + */ +#include <pjsip/sip_msg.h> + +/** + * @ingroup PJSIP_EVENT_NOT + * @{ + */ + +PJ_BEGIN_DECL + + +/** Max events in Allow-Events header. */ +#define PJSIP_MAX_ALLOW_EVENTS 16 + +/** + * This structure describes Event header. + */ +typedef struct pjsip_event_hdr +{ + PJSIP_DECL_HDR_MEMBER(struct pjsip_event_hdr) + pj_str_t event_type; /**< Event name. */ + pj_str_t id_param; /**< Optional event ID parameter. */ + pj_str_t other_param; /**< Other parameter, concatenated together. */ +} pjsip_event_hdr; + +/** + * Create an Event header. + * + * @param pool The pool. + * + * @return New Event header instance. + */ +PJ_DECL(pjsip_event_hdr*) pjsip_event_hdr_create(pj_pool_t *pool); + + +/** + * This structure describes Allow-Events header. + */ +typedef struct pjsip_allow_events_hdr +{ + PJSIP_DECL_HDR_MEMBER(struct pjsip_allow_events_hdr) + int event_cnt; /**< Number of event names. */ + pj_str_t events[PJSIP_MAX_ALLOW_EVENTS]; /**< Event names. */ +} pjsip_allow_events_hdr; + + +/** + * Create a new Allow-Events header. + * + * @param pool. The pool. + * + * @return Allow-Events header. + */ +PJ_DECL(pjsip_allow_events_hdr*) pjsip_allow_events_hdr_create(pj_pool_t *pool); + + +/** + * This structure describes Subscription-State header. + */ +typedef struct pjsip_sub_state_hdr +{ + PJSIP_DECL_HDR_MEMBER(struct pjsip_sub_state_hdr) + pj_str_t sub_state; /**< Subscription state. */ + pj_str_t reason_param; /**< Optional termination reason. */ + int expires_param; /**< Expires param, or -1. */ + int retry_after; /**< Retry after param, or -1. */ + pj_str_t other_param; /**< Other parameter, concatenated together. */ +} pjsip_sub_state_hdr; + +/** + * Create new Subscription-State header. + * + * @param pool The pool. + * + * @return Subscription-State header. + */ +PJ_DECL(pjsip_sub_state_hdr*) pjsip_sub_state_hdr_create(pj_pool_t *pool); + +/** + * Initialize parser for event notify module. + */ +PJ_DEF(void) pjsip_event_notify_init_parser(void); + + +PJ_END_DECL + + +/** + * @} + */ + +#endif /* __PJSIP_SIMPLE_EVENT_NOTIFY_MSG_H__ */ + diff --git a/pjsip/include/pjsip-simple/messaging.h b/pjsip/include/pjsip-simple/messaging.h index 25bf5dd5..742d739c 100644 --- a/pjsip/include/pjsip-simple/messaging.h +++ b/pjsip/include/pjsip-simple/messaging.h @@ -1,268 +1,268 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIMPLE_MESSAGING_H__
-#define __PJSIP_SIMPLE_MESSAGING_H__
-
-/**
- * @file messaging.h
- * @brief Instant Messaging Extension (RFC 3428)
- */
-
-#include <pjsip/sip_msg.h>
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJSIP_MESSAGING SIP Instant Messaging (RFC 3428) Module
- * @ingroup PJSIP_SIMPLE
- * @{
- *
- * This module provides the implementation of SIP Extension for Instant
- * Messaging (RFC 3428). It extends PJSIP by supporting MESSAGE method.
- *
- * The RFC 3428 doesn't provide any means of dialog for the purpose of sending/
- * receiving instant messaging. IM with SIP is basicly sessionless, which means
- * that there is absolutely no correlation between IM messages sent or received
- * by a host. Any correlation between IM messages is only perceivable by
- * user, phsychologically.
- *
- * However, the RFC doesn't prohibit sending IM within a dialog (presumably
- * using the same Call-ID and CSeq namespace), although it prohibits creating
- * a dialog specificly for creating IM session.
- *
- * The implementation here is modeled to support both ways of sending IM msgs,
- * i.e. sending IM message individually and sending IM message within a dialog.
- * Although IM message can be associated with a dialog, this implementation of
- * IM module is completely independent of the User Agent library in PJSIP. Yes,
- * that's what is called modularity, and it demonstrates the clearness
- * of PJSIP design (the last sentence is of course marketing crap :)).
- *
- * To send an IM message as part of dialog, application would first create the
- * message using #pjsip_messaging_create_msg, using dialog's Call-ID, CSeq,
- * From, and To header, then send the message using #pjsip_dlg_send_msg instead
- * of #pjsip_messaging_send_msg.
- *
- * To send IM messages individually, application has two options. The first is
- * to create the request with #pjsip_messaging_create_msg then send it with
- * #pjsip_messaging_send_msg. But this way, application has to pre-construct
- * From and To header first, which is not too convenient.
- *
- * The second option (to send IM messages not associated with a dialog) is to
- * first create an 'IM session'. An 'IM session' here is not a SIP dialog, as
- * it doesn't have Contact header etc. An 'IM session' here is just a local
- * state to cache most of IM headers, for convenience and optimization. Appl
- * creates an IM session with #pjsip_messaging_create_session, and destroy
- * the session with #pjsip_messaging_destroy_session. To create an outgoing
- * IM message, application would call #pjsip_messaging_session_create_msg,
- * and to send the message it would use #pjsip_messaging_send_msg.
- *
- * Message authorization is handled by application, as usual, by inserting a
- * proper WWW-Authenticate or Proxy-Authenticate header before sending the
- * message.
- *
- * And the last bit, to handle incoing IM messages.
- *
- * To handle incoming IM messages, application would register a global callback
- * to be called when incoming messages arrive, by registering with function
- * #pjsip_messaging_set_incoming_callback. This will be the global callback
- * for all incoming IM messages. Although the message was sent as part of
- * a dialog, it would still come here. And as long as the request has proper
- * identification (Call-ID, From/To tag), the dialog will be aware of the
- * request and update it's state (remote CSeq) accordingly.
- */
-
-
-
-/**
- * Typedef for callback to be called when outgoing message has been sent
- * and a final response has been received.
- */
-typedef void (*pjsip_messaging_cb)(void *token, int status_code);
-
-/**
- * Typedef for callback to receive incoming message.
- *
- * @param rdata Incoming message data.
- *
- * @return The status code to be returned back to original sender.
- * Application must return a final status code upon returning
- * from this function, or otherwise the stack will respond
- * with error.
- */
-typedef int (*pjsip_on_new_msg_cb)(pjsip_rx_data *rdata);
-
-/**
- * Opaque data type for instant messaging session.
- */
-typedef struct pjsip_messaging_session pjsip_messaging_session;
-
-/**
- * Get the messaging module.
- *
- * @return SIP module.
- */
-PJ_DECL(pjsip_module*) pjsip_messaging_get_module();
-
-/**
- * Set the global callback to be called when incoming message is received.
- *
- * @param cb The callback to be called when incoming message is received.
- *
- * @return The previous callback.
- */
-PJ_DECL(pjsip_on_new_msg_cb)
-pjsip_messaging_set_incoming_callback(pjsip_on_new_msg_cb cb);
-
-
-/**
- * Create an instant message transmit data buffer using the specified arguments.
- * The returned transmit data buffers will have it's reference counter set
- * to 1, and when application send the buffer, the send function will decrement
- * the reference counter. When the reference counter reach zero, the buffer
- * will be deleted. As long as the function does not increment the buffer's
- * reference counter between creating and sending the request, the buffer
- * will always be deleted and no memory leak will occur.
- *
- * @param endpt Endpoint instance.
- * @param target Target URL.
- * @param from The "From" header, which content will be copied to request.
- * If the "From" header doesn't have a tag parameter, the
- * function will generate one.
- * @param to The "To" header, which content will be copied to request.
- * @param call_id Optionally specify Call-ID, or put NULL to make this
- * function generate a unique Call-ID automatically.
- * @param cseq Optionally specify CSeq, or put -1 to make this function
- * generate a random CSeq.
- * @param text Optionally specify "text/plain" message body, or put NULL
- * if application wants to put body other than "text/plain"
- * manually.
- *
- * @return SIP transmit data buffer, which reference count has been
- * set to 1.
- */
-PJ_DECL(pjsip_tx_data*)
-pjsip_messaging_create_msg_from_hdr(pjsip_endpoint *endpt,
- const pjsip_uri *target,
- const pjsip_from_hdr *from,
- const pjsip_to_hdr *to,
- const pjsip_cid_hdr *call_id,
- int cseq,
- const pj_str_t *text);
-
-/**
- * Create instant message, by specifying URL string for both From and To header.
- *
- * @param endpt Endpoint instance.
- * @param target Target URL.
- * @param from URL of the sender.
- * @param to URL of the recipient.
- * @param call_id Optionally specify Call-ID, or put NULL to make this
- * function generate a unique Call-ID automatically.
- * @param cseq Optionally specify CSeq, or put -1 to make this function
- * generate a random CSeq.
- * @param text Optionally specify "text/plain" message body, or put NULL
- * if application wants to put body other than "text/plain"
- * manually.
- *
- * @return SIP transmit data buffer, which reference count has been
- * set to 1.
- */
-PJ_DECL(pjsip_tx_data*) pjsip_messaging_create_msg( pjsip_endpoint *endpt,
- const pj_str_t *target,
- const pj_str_t *from,
- const pj_str_t *to,
- const pj_str_t *call_id,
- int cseq,
- const pj_str_t *text);
-
-/**
- * Send the instant message transmit buffer and attach a callback to be called
- * when the request has received a final response. This function will decrement
- * the transmit buffer's reference counter, and when the reference counter
- * reach zero, the buffer will be deleted. As long as the function does not
- * increment the buffer's reference counter between creating the request and
- * calling this function, the buffer will always be deleted regardless whether
- * the sending was failed or succeeded.
- *
- * @param endpt Endpoint instance.
- * @param tdata Transmit data buffer.
- * @param token Token to be associated with the SIP transaction which sends
- * this request.
- * @param cb The callback to be called when the SIP request has received
- * a final response from destination.
- *
- * @return Zero if the transaction was started successfully. Note that
- * this doesn't mean the request has been received successfully
- * by remote recipient.
- */
-PJ_DECL(pj_status_t) pjsip_messaging_send_msg( pjsip_endpoint *endpt,
- pjsip_tx_data *tdata,
- void *token,
- pjsip_messaging_cb cb );
-
-/**
- * Create an instant messaging session, which can conveniently be used to send
- * multiple instant messages to the same recipient.
- *
- * @param endpt Endpoint instance.
- * @param from URI of sender. The function will add a unique tag parameter
- * to this URI in the From header.
- * @param to URI of recipient.
- *
- * @return Messaging session.
- */
-PJ_DECL(pjsip_messaging_session*)
-pjsip_messaging_create_session( pjsip_endpoint *endpt,
- const pj_str_t *from,
- const pj_str_t *to );
-
-/**
- * Create an instant message using instant messaging session, and optionally
- * attach a text message.
- *
- * @param ses The instant messaging session.
- * @param text Optional "text/plain" message to be attached as the
- * message body. If this parameter is NULL, then no message
- * body will be created, and application can attach any
- * type of message body before the request is sent.
- *
- * @return SIP transmit data buffer, which reference counter has been
- * set to 1.
- */
-PJ_DECL(pjsip_tx_data*)
-pjsip_messaging_session_create_msg( pjsip_messaging_session *ses,
- const pj_str_t *text );
-
-/**
- * Destroy an instant messaging session.
- *
- * @param ses The instant messaging session.
- *
- * @return Zero on successfull.
- */
-PJ_DECL(pj_status_t)
-pjsip_messaging_destroy_session( pjsip_messaging_session *ses );
-
-/**
- * @}
- */
-
-PJ_END_DECL
-
-#endif
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIMPLE_MESSAGING_H__ +#define __PJSIP_SIMPLE_MESSAGING_H__ + +/** + * @file messaging.h + * @brief Instant Messaging Extension (RFC 3428) + */ + +#include <pjsip/sip_msg.h> + +PJ_BEGIN_DECL + +/** + * @defgroup PJSIP_MESSAGING SIP Instant Messaging (RFC 3428) Module + * @ingroup PJSIP_SIMPLE + * @{ + * + * This module provides the implementation of SIP Extension for Instant + * Messaging (RFC 3428). It extends PJSIP by supporting MESSAGE method. + * + * The RFC 3428 doesn't provide any means of dialog for the purpose of sending/ + * receiving instant messaging. IM with SIP is basicly sessionless, which means + * that there is absolutely no correlation between IM messages sent or received + * by a host. Any correlation between IM messages is only perceivable by + * user, phsychologically. + * + * However, the RFC doesn't prohibit sending IM within a dialog (presumably + * using the same Call-ID and CSeq namespace), although it prohibits creating + * a dialog specificly for creating IM session. + * + * The implementation here is modeled to support both ways of sending IM msgs, + * i.e. sending IM message individually and sending IM message within a dialog. + * Although IM message can be associated with a dialog, this implementation of + * IM module is completely independent of the User Agent library in PJSIP. Yes, + * that's what is called modularity, and it demonstrates the clearness + * of PJSIP design (the last sentence is of course marketing crap :)). + * + * To send an IM message as part of dialog, application would first create the + * message using #pjsip_messaging_create_msg, using dialog's Call-ID, CSeq, + * From, and To header, then send the message using #pjsip_dlg_send_msg instead + * of #pjsip_messaging_send_msg. + * + * To send IM messages individually, application has two options. The first is + * to create the request with #pjsip_messaging_create_msg then send it with + * #pjsip_messaging_send_msg. But this way, application has to pre-construct + * From and To header first, which is not too convenient. + * + * The second option (to send IM messages not associated with a dialog) is to + * first create an 'IM session'. An 'IM session' here is not a SIP dialog, as + * it doesn't have Contact header etc. An 'IM session' here is just a local + * state to cache most of IM headers, for convenience and optimization. Appl + * creates an IM session with #pjsip_messaging_create_session, and destroy + * the session with #pjsip_messaging_destroy_session. To create an outgoing + * IM message, application would call #pjsip_messaging_session_create_msg, + * and to send the message it would use #pjsip_messaging_send_msg. + * + * Message authorization is handled by application, as usual, by inserting a + * proper WWW-Authenticate or Proxy-Authenticate header before sending the + * message. + * + * And the last bit, to handle incoing IM messages. + * + * To handle incoming IM messages, application would register a global callback + * to be called when incoming messages arrive, by registering with function + * #pjsip_messaging_set_incoming_callback. This will be the global callback + * for all incoming IM messages. Although the message was sent as part of + * a dialog, it would still come here. And as long as the request has proper + * identification (Call-ID, From/To tag), the dialog will be aware of the + * request and update it's state (remote CSeq) accordingly. + */ + + + +/** + * Typedef for callback to be called when outgoing message has been sent + * and a final response has been received. + */ +typedef void (*pjsip_messaging_cb)(void *token, int status_code); + +/** + * Typedef for callback to receive incoming message. + * + * @param rdata Incoming message data. + * + * @return The status code to be returned back to original sender. + * Application must return a final status code upon returning + * from this function, or otherwise the stack will respond + * with error. + */ +typedef int (*pjsip_on_new_msg_cb)(pjsip_rx_data *rdata); + +/** + * Opaque data type for instant messaging session. + */ +typedef struct pjsip_messaging_session pjsip_messaging_session; + +/** + * Get the messaging module. + * + * @return SIP module. + */ +PJ_DECL(pjsip_module*) pjsip_messaging_get_module(); + +/** + * Set the global callback to be called when incoming message is received. + * + * @param cb The callback to be called when incoming message is received. + * + * @return The previous callback. + */ +PJ_DECL(pjsip_on_new_msg_cb) +pjsip_messaging_set_incoming_callback(pjsip_on_new_msg_cb cb); + + +/** + * Create an instant message transmit data buffer using the specified arguments. + * The returned transmit data buffers will have it's reference counter set + * to 1, and when application send the buffer, the send function will decrement + * the reference counter. When the reference counter reach zero, the buffer + * will be deleted. As long as the function does not increment the buffer's + * reference counter between creating and sending the request, the buffer + * will always be deleted and no memory leak will occur. + * + * @param endpt Endpoint instance. + * @param target Target URL. + * @param from The "From" header, which content will be copied to request. + * If the "From" header doesn't have a tag parameter, the + * function will generate one. + * @param to The "To" header, which content will be copied to request. + * @param call_id Optionally specify Call-ID, or put NULL to make this + * function generate a unique Call-ID automatically. + * @param cseq Optionally specify CSeq, or put -1 to make this function + * generate a random CSeq. + * @param text Optionally specify "text/plain" message body, or put NULL + * if application wants to put body other than "text/plain" + * manually. + * + * @return SIP transmit data buffer, which reference count has been + * set to 1. + */ +PJ_DECL(pjsip_tx_data*) +pjsip_messaging_create_msg_from_hdr(pjsip_endpoint *endpt, + const pjsip_uri *target, + const pjsip_from_hdr *from, + const pjsip_to_hdr *to, + const pjsip_cid_hdr *call_id, + int cseq, + const pj_str_t *text); + +/** + * Create instant message, by specifying URL string for both From and To header. + * + * @param endpt Endpoint instance. + * @param target Target URL. + * @param from URL of the sender. + * @param to URL of the recipient. + * @param call_id Optionally specify Call-ID, or put NULL to make this + * function generate a unique Call-ID automatically. + * @param cseq Optionally specify CSeq, or put -1 to make this function + * generate a random CSeq. + * @param text Optionally specify "text/plain" message body, or put NULL + * if application wants to put body other than "text/plain" + * manually. + * + * @return SIP transmit data buffer, which reference count has been + * set to 1. + */ +PJ_DECL(pjsip_tx_data*) pjsip_messaging_create_msg( pjsip_endpoint *endpt, + const pj_str_t *target, + const pj_str_t *from, + const pj_str_t *to, + const pj_str_t *call_id, + int cseq, + const pj_str_t *text); + +/** + * Send the instant message transmit buffer and attach a callback to be called + * when the request has received a final response. This function will decrement + * the transmit buffer's reference counter, and when the reference counter + * reach zero, the buffer will be deleted. As long as the function does not + * increment the buffer's reference counter between creating the request and + * calling this function, the buffer will always be deleted regardless whether + * the sending was failed or succeeded. + * + * @param endpt Endpoint instance. + * @param tdata Transmit data buffer. + * @param token Token to be associated with the SIP transaction which sends + * this request. + * @param cb The callback to be called when the SIP request has received + * a final response from destination. + * + * @return Zero if the transaction was started successfully. Note that + * this doesn't mean the request has been received successfully + * by remote recipient. + */ +PJ_DECL(pj_status_t) pjsip_messaging_send_msg( pjsip_endpoint *endpt, + pjsip_tx_data *tdata, + void *token, + pjsip_messaging_cb cb ); + +/** + * Create an instant messaging session, which can conveniently be used to send + * multiple instant messages to the same recipient. + * + * @param endpt Endpoint instance. + * @param from URI of sender. The function will add a unique tag parameter + * to this URI in the From header. + * @param to URI of recipient. + * + * @return Messaging session. + */ +PJ_DECL(pjsip_messaging_session*) +pjsip_messaging_create_session( pjsip_endpoint *endpt, + const pj_str_t *from, + const pj_str_t *to ); + +/** + * Create an instant message using instant messaging session, and optionally + * attach a text message. + * + * @param ses The instant messaging session. + * @param text Optional "text/plain" message to be attached as the + * message body. If this parameter is NULL, then no message + * body will be created, and application can attach any + * type of message body before the request is sent. + * + * @return SIP transmit data buffer, which reference counter has been + * set to 1. + */ +PJ_DECL(pjsip_tx_data*) +pjsip_messaging_session_create_msg( pjsip_messaging_session *ses, + const pj_str_t *text ); + +/** + * Destroy an instant messaging session. + * + * @param ses The instant messaging session. + * + * @return Zero on successfull. + */ +PJ_DECL(pj_status_t) +pjsip_messaging_destroy_session( pjsip_messaging_session *ses ); + +/** + * @} + */ + +PJ_END_DECL + +#endif diff --git a/pjsip/include/pjsip-simple/pidf.h b/pjsip/include/pjsip-simple/pidf.h index 70e12907..b9dd4509 100644 --- a/pjsip/include/pjsip-simple/pidf.h +++ b/pjsip/include/pjsip-simple/pidf.h @@ -1,176 +1,176 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIMPLE_PIDF_H__
-#define __PJSIP_SIMPLE_PIDF_H__
-
-/**
- * @file pidf.h
- * @brief PIDF/Presence Information Data Format (RFC 3863)
- */
-#include <pj/types.h>
-#include <pj/xml.h>
-
-PJ_BEGIN_DECL
-
-
-/**
- * @defgroup PJSIP_SIMPLE_PIDF PIDF/Presence Information Data Format (RFC 3863)
- * @ingroup PJSIP_SIMPLE
- * @{
- *
- * This file provides tools for manipulating Presence Information Data
- * Format (PIDF) as described in RFC 3863.
- */
-typedef struct pj_xml_node pjpidf_pres;
-typedef struct pj_xml_node pjpidf_tuple;
-typedef struct pj_xml_node pjpidf_status;
-typedef struct pj_xml_node pjpidf_note;
-
-typedef struct pjpidf_status_op
-{
- void (*construct)(pj_pool_t*, pjpidf_status*);
- pj_bool_t (*is_basic_open)(const pjpidf_status*);
- void (*set_basic_open)(pjpidf_status*, pj_bool_t);
-} pjpidf_status_op;
-
-typedef struct pjpidf_tuple_op
-{
- void (*construct)(pj_pool_t*, pjpidf_tuple*, const pj_str_t*);
-
- const pj_str_t* (*get_id)(const pjpidf_tuple* );
- void (*set_id)(pj_pool_t*, pjpidf_tuple *, const pj_str_t*);
-
- pjpidf_status* (*get_status)(pjpidf_tuple* );
-
- const pj_str_t* (*get_contact)(const pjpidf_tuple*);
- void (*set_contact)(pj_pool_t*, pjpidf_tuple*, const pj_str_t*);
- void (*set_contact_prio)(pj_pool_t*, pjpidf_tuple*, const pj_str_t*);
- const pj_str_t* (*get_contact_prio)(const pjpidf_tuple*);
-
- pjpidf_note* (*add_note)(pj_pool_t*, pjpidf_tuple*, const pj_str_t*);
- pjpidf_note* (*get_first_note)(pjpidf_tuple*);
- pjpidf_note* (*get_next_note)(pjpidf_tuple*, pjpidf_note*);
-
- const pj_str_t* (*get_timestamp)(const pjpidf_tuple*);
- void (*set_timestamp)(pj_pool_t*, pjpidf_tuple*, const pj_str_t*);
- void (*set_timestamp_np)(pj_pool_t*,pjpidf_tuple*, pj_str_t*);
-
-} pjpidf_tuple_op;
-
-typedef struct pjpidf_pres_op
-{
- void (*construct)(pj_pool_t*, pjpidf_pres*, const pj_str_t*);
-
- pjpidf_tuple* (*add_tuple)(pj_pool_t*, pjpidf_pres*, const pj_str_t*);
- pjpidf_tuple* (*get_first_tuple)(pjpidf_pres*);
- pjpidf_tuple* (*get_next_tuple)(pjpidf_pres*, pjpidf_tuple*);
- pjpidf_tuple* (*find_tuple)(pjpidf_pres*, const pj_str_t*);
- void (*remove_tuple)(pjpidf_pres*, pjpidf_tuple*);
-
- pjpidf_note* (*add_note)(pj_pool_t*, pjpidf_pres*, const pj_str_t*);
- pjpidf_note* (*get_first_note)(pjpidf_pres*);
- pjpidf_note* (*get_next_note)(pjpidf_pres*, pjpidf_note*);
-
-} pjpidf_pres_op;
-
-
-extern struct pjpidf_op_desc
-{
- pjpidf_pres_op pres;
- pjpidf_tuple_op tuple;
- pjpidf_status_op status;
-} pjpidf_op;
-
-
-/******************************************************************************
- * Top level API for managing presence document.
- *****************************************************************************/
-PJ_DECL(pjpidf_pres*) pjpidf_create(pj_pool_t *pool, const pj_str_t *entity);
-PJ_DECL(pjpidf_pres*) pjpidf_parse(pj_pool_t *pool, char *text, int len);
-PJ_DECL(int) pjpidf_print(const pjpidf_pres* pres, char *buf, int len);
-
-
-/******************************************************************************
- * API for managing Presence node.
- *****************************************************************************/
-PJ_DECL(void) pjpidf_pres_construct(pj_pool_t *pool, pjpidf_pres *pres,
- const pj_str_t *entity);
-PJ_DECL(pjpidf_tuple*) pjpidf_pres_add_tuple(pj_pool_t *pool, pjpidf_pres *pres,
- const pj_str_t *id);
-PJ_DECL(pjpidf_tuple*) pjpidf_pres_get_first_tuple(pjpidf_pres *pres);
-PJ_DECL(pjpidf_tuple*) pjpidf_pres_get_next_tuple(pjpidf_pres *pres,
- pjpidf_tuple *t);
-PJ_DECL(pjpidf_tuple*) pjpidf_pres_find_tuple(pjpidf_pres *pres,
- const pj_str_t *id);
-PJ_DECL(void) pjpidf_pres_remove_tuple(pjpidf_pres *pres,
- pjpidf_tuple*);
-
-PJ_DECL(pjpidf_note*) pjpidf_pres_add_note(pj_pool_t *pool, pjpidf_pres *pres,
- const pj_str_t *text);
-PJ_DECL(pjpidf_note*) pjpidf_pres_get_first_note(pjpidf_pres *pres);
-PJ_DECL(pjpidf_note*) pjpidf_pres_get_next_note(pjpidf_pres*, pjpidf_note*);
-
-
-/******************************************************************************
- * API for managing Tuple node.
- *****************************************************************************/
-PJ_DECL(void) pjpidf_tuple_construct(pj_pool_t *pool, pjpidf_tuple *t,
- const pj_str_t *id);
-PJ_DECL(const pj_str_t*) pjpidf_tuple_get_id(const pjpidf_tuple *t );
-PJ_DECL(void) pjpidf_tuple_set_id(pj_pool_t *pool, pjpidf_tuple *t,
- const pj_str_t *id);
-
-PJ_DECL(pjpidf_status*) pjpidf_tuple_get_status(pjpidf_tuple *t);
-
-PJ_DECL(const pj_str_t*) pjpidf_tuple_get_contact(const pjpidf_tuple *t);
-PJ_DECL(void) pjpidf_tuple_set_contact(pj_pool_t *pool, pjpidf_tuple *t,
- const pj_str_t *contact);
-PJ_DECL(void) pjpidf_tuple_set_contact_prio(pj_pool_t *pool, pjpidf_tuple *t,
- const pj_str_t *prio);
-PJ_DECL(const pj_str_t*) pjpidf_tuple_get_contact_prio(const pjpidf_tuple *t);
-
-PJ_DECL(pjpidf_note*) pjpidf_tuple_add_note(pj_pool_t *pool, pjpidf_tuple *t,
- const pj_str_t *text);
-PJ_DECL(pjpidf_note*) pjpidf_tuple_get_first_note(pjpidf_tuple *t);
-PJ_DECL(pjpidf_note*) pjpidf_tuple_get_next_note(pjpidf_tuple *t, pjpidf_note *n);
-
-PJ_DECL(const pj_str_t*) pjpidf_tuple_get_timestamp(const pjpidf_tuple *t);
-PJ_DECL(void) pjpidf_tuple_set_timestamp(pj_pool_t *pool, pjpidf_tuple *t,
- const pj_str_t *ts);
-PJ_DECL(void) pjpidf_tuple_set_timestamp_np( pj_pool_t*, pjpidf_tuple *t,
- pj_str_t *ts);
-
-
-/******************************************************************************
- * API for managing Status node.
- *****************************************************************************/
-PJ_DECL(void) pjpidf_status_construct(pj_pool_t*, pjpidf_status*);
-PJ_DECL(pj_bool_t) pjpidf_status_is_basic_open(const pjpidf_status*);
-PJ_DECL(void) pjpidf_status_set_basic_open(pjpidf_status*, pj_bool_t);
-
-
-/**
- * @}
- */
-
-
-PJ_END_DECL
-
-
-#endif /* __PJSIP_SIMPLE_PIDF_H__ */
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIMPLE_PIDF_H__ +#define __PJSIP_SIMPLE_PIDF_H__ + +/** + * @file pidf.h + * @brief PIDF/Presence Information Data Format (RFC 3863) + */ +#include <pj/types.h> +#include <pj/xml.h> + +PJ_BEGIN_DECL + + +/** + * @defgroup PJSIP_SIMPLE_PIDF PIDF/Presence Information Data Format (RFC 3863) + * @ingroup PJSIP_SIMPLE + * @{ + * + * This file provides tools for manipulating Presence Information Data + * Format (PIDF) as described in RFC 3863. + */ +typedef struct pj_xml_node pjpidf_pres; +typedef struct pj_xml_node pjpidf_tuple; +typedef struct pj_xml_node pjpidf_status; +typedef struct pj_xml_node pjpidf_note; + +typedef struct pjpidf_status_op +{ + void (*construct)(pj_pool_t*, pjpidf_status*); + pj_bool_t (*is_basic_open)(const pjpidf_status*); + void (*set_basic_open)(pjpidf_status*, pj_bool_t); +} pjpidf_status_op; + +typedef struct pjpidf_tuple_op +{ + void (*construct)(pj_pool_t*, pjpidf_tuple*, const pj_str_t*); + + const pj_str_t* (*get_id)(const pjpidf_tuple* ); + void (*set_id)(pj_pool_t*, pjpidf_tuple *, const pj_str_t*); + + pjpidf_status* (*get_status)(pjpidf_tuple* ); + + const pj_str_t* (*get_contact)(const pjpidf_tuple*); + void (*set_contact)(pj_pool_t*, pjpidf_tuple*, const pj_str_t*); + void (*set_contact_prio)(pj_pool_t*, pjpidf_tuple*, const pj_str_t*); + const pj_str_t* (*get_contact_prio)(const pjpidf_tuple*); + + pjpidf_note* (*add_note)(pj_pool_t*, pjpidf_tuple*, const pj_str_t*); + pjpidf_note* (*get_first_note)(pjpidf_tuple*); + pjpidf_note* (*get_next_note)(pjpidf_tuple*, pjpidf_note*); + + const pj_str_t* (*get_timestamp)(const pjpidf_tuple*); + void (*set_timestamp)(pj_pool_t*, pjpidf_tuple*, const pj_str_t*); + void (*set_timestamp_np)(pj_pool_t*,pjpidf_tuple*, pj_str_t*); + +} pjpidf_tuple_op; + +typedef struct pjpidf_pres_op +{ + void (*construct)(pj_pool_t*, pjpidf_pres*, const pj_str_t*); + + pjpidf_tuple* (*add_tuple)(pj_pool_t*, pjpidf_pres*, const pj_str_t*); + pjpidf_tuple* (*get_first_tuple)(pjpidf_pres*); + pjpidf_tuple* (*get_next_tuple)(pjpidf_pres*, pjpidf_tuple*); + pjpidf_tuple* (*find_tuple)(pjpidf_pres*, const pj_str_t*); + void (*remove_tuple)(pjpidf_pres*, pjpidf_tuple*); + + pjpidf_note* (*add_note)(pj_pool_t*, pjpidf_pres*, const pj_str_t*); + pjpidf_note* (*get_first_note)(pjpidf_pres*); + pjpidf_note* (*get_next_note)(pjpidf_pres*, pjpidf_note*); + +} pjpidf_pres_op; + + +extern struct pjpidf_op_desc +{ + pjpidf_pres_op pres; + pjpidf_tuple_op tuple; + pjpidf_status_op status; +} pjpidf_op; + + +/****************************************************************************** + * Top level API for managing presence document. + *****************************************************************************/ +PJ_DECL(pjpidf_pres*) pjpidf_create(pj_pool_t *pool, const pj_str_t *entity); +PJ_DECL(pjpidf_pres*) pjpidf_parse(pj_pool_t *pool, char *text, int len); +PJ_DECL(int) pjpidf_print(const pjpidf_pres* pres, char *buf, int len); + + +/****************************************************************************** + * API for managing Presence node. + *****************************************************************************/ +PJ_DECL(void) pjpidf_pres_construct(pj_pool_t *pool, pjpidf_pres *pres, + const pj_str_t *entity); +PJ_DECL(pjpidf_tuple*) pjpidf_pres_add_tuple(pj_pool_t *pool, pjpidf_pres *pres, + const pj_str_t *id); +PJ_DECL(pjpidf_tuple*) pjpidf_pres_get_first_tuple(pjpidf_pres *pres); +PJ_DECL(pjpidf_tuple*) pjpidf_pres_get_next_tuple(pjpidf_pres *pres, + pjpidf_tuple *t); +PJ_DECL(pjpidf_tuple*) pjpidf_pres_find_tuple(pjpidf_pres *pres, + const pj_str_t *id); +PJ_DECL(void) pjpidf_pres_remove_tuple(pjpidf_pres *pres, + pjpidf_tuple*); + +PJ_DECL(pjpidf_note*) pjpidf_pres_add_note(pj_pool_t *pool, pjpidf_pres *pres, + const pj_str_t *text); +PJ_DECL(pjpidf_note*) pjpidf_pres_get_first_note(pjpidf_pres *pres); +PJ_DECL(pjpidf_note*) pjpidf_pres_get_next_note(pjpidf_pres*, pjpidf_note*); + + +/****************************************************************************** + * API for managing Tuple node. + *****************************************************************************/ +PJ_DECL(void) pjpidf_tuple_construct(pj_pool_t *pool, pjpidf_tuple *t, + const pj_str_t *id); +PJ_DECL(const pj_str_t*) pjpidf_tuple_get_id(const pjpidf_tuple *t ); +PJ_DECL(void) pjpidf_tuple_set_id(pj_pool_t *pool, pjpidf_tuple *t, + const pj_str_t *id); + +PJ_DECL(pjpidf_status*) pjpidf_tuple_get_status(pjpidf_tuple *t); + +PJ_DECL(const pj_str_t*) pjpidf_tuple_get_contact(const pjpidf_tuple *t); +PJ_DECL(void) pjpidf_tuple_set_contact(pj_pool_t *pool, pjpidf_tuple *t, + const pj_str_t *contact); +PJ_DECL(void) pjpidf_tuple_set_contact_prio(pj_pool_t *pool, pjpidf_tuple *t, + const pj_str_t *prio); +PJ_DECL(const pj_str_t*) pjpidf_tuple_get_contact_prio(const pjpidf_tuple *t); + +PJ_DECL(pjpidf_note*) pjpidf_tuple_add_note(pj_pool_t *pool, pjpidf_tuple *t, + const pj_str_t *text); +PJ_DECL(pjpidf_note*) pjpidf_tuple_get_first_note(pjpidf_tuple *t); +PJ_DECL(pjpidf_note*) pjpidf_tuple_get_next_note(pjpidf_tuple *t, pjpidf_note *n); + +PJ_DECL(const pj_str_t*) pjpidf_tuple_get_timestamp(const pjpidf_tuple *t); +PJ_DECL(void) pjpidf_tuple_set_timestamp(pj_pool_t *pool, pjpidf_tuple *t, + const pj_str_t *ts); +PJ_DECL(void) pjpidf_tuple_set_timestamp_np( pj_pool_t*, pjpidf_tuple *t, + pj_str_t *ts); + + +/****************************************************************************** + * API for managing Status node. + *****************************************************************************/ +PJ_DECL(void) pjpidf_status_construct(pj_pool_t*, pjpidf_status*); +PJ_DECL(pj_bool_t) pjpidf_status_is_basic_open(const pjpidf_status*); +PJ_DECL(void) pjpidf_status_set_basic_open(pjpidf_status*, pj_bool_t); + + +/** + * @} + */ + + +PJ_END_DECL + + +#endif /* __PJSIP_SIMPLE_PIDF_H__ */ diff --git a/pjsip/include/pjsip-simple/presence.h b/pjsip/include/pjsip-simple/presence.h index e4f34274..180ac4d1 100644 --- a/pjsip/include/pjsip-simple/presence.h +++ b/pjsip/include/pjsip-simple/presence.h @@ -1,229 +1,229 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIMPLE_PRESENCE_H__
-#define __PJSIP_SIMPLE_PRESENCE_H__
-
-/**
- * @file presence.h
- * @brief SIP Extension for Presence (RFC 3856)
- */
-#include <pjsip_simple/event_notify.h>
-#include <pjsip_simple/pidf.h>
-#include <pjsip_simple/xpidf.h>
-
-
-PJ_BEGIN_DECL
-
-
-/**
- * @defgroup PJSIP_SIMPLE_PRES SIP Extension for Presence (RFC 3856)
- * @ingroup PJSIP_SIMPLE
- * @{
- *
- * This module contains the implementation of SIP Presence Extension as
- * described in RFC 3856. It uses the SIP Event Notification framework
- * (event_notify.h) and extends the framework by implementing "presence"
- * event package.
- */
-
-/**
- * Presence message body type.
- */
-typedef enum pjsip_pres_type
-{
- PJSIP_PRES_TYPE_PIDF,
- PJSIP_PRES_TYPE_XPIDF,
-} pjsip_pres_type;
-
-/**
- * This structure describe a presentity, for both subscriber and notifier.
- */
-typedef struct pjsip_presentity
-{
- pjsip_event_sub *sub; /**< Event subscribtion record. */
- pjsip_pres_type pres_type; /**< Presentity type. */
- pjsip_msg_body *uas_body; /**< Message body (UAS only). */
- union {
- pjpidf_pres *pidf;
- pjxpidf_pres *xpidf;
- } uas_data; /**< UAS data. */
- pj_str_t timestamp; /**< Time of last update. */
- void *user_data; /**< Application data. */
-} pjsip_presentity;
-
-
-/**
- * This structure describe callback that is registered to receive notification
- * from the presence module.
- */
-typedef struct pjsip_presence_cb
-{
- /**
- * This callback is first called when the module receives incoming
- * SUBSCRIBE request to determine whether application wants to accept
- * the request. If it does, then on_presence_request will be called.
- *
- * @param rdata The received message.
- * @return Application should return 2xx to accept the request,
- * or failure status (>=300) to reject the request.
- */
- void (*accept_presence)(pjsip_rx_data *rdata, int *status);
-
- /**
- * This callback is called when the module receive the first presence
- * subscription request.
- *
- * @param pres The presence descriptor.
- * @param rdata The incoming request.
- * @param timeout Timeout to be set for incoming request. Otherwise
- * app can just leave this and accept the default.
- */
- void (*on_received_request)(pjsip_presentity *pres, pjsip_rx_data *rdata,
- int *timeout);
-
- /**
- * This callback is called when the module received subscription refresh
- * request.
- *
- * @param pres The presence descriptor.
- * @param rdata The incoming request.
- */
- void (*on_received_refresh)(pjsip_presentity *pres, pjsip_rx_data *rdata);
-
- /**
- * This callback is called when the module receives incoming NOTIFY
- * request.
- *
- * @param pres The presence descriptor.
- * @param open The latest status of the presentity.
- */
- void (*on_received_update)(pjsip_presentity *pres, pj_bool_t open);
-
- /**
- * This callback is called when the subscription has terminated.
- *
- * @param sub The subscription instance.
- * @param reason The termination reason.
- */
- void (*on_terminated)(pjsip_presentity *pres, const pj_str_t *reason);
-
-} pjsip_presence_cb;
-
-
-/**
- * Initialize the presence module and register callback.
- *
- * @param cb Callback structure.
- */
-PJ_DECL(void) pjsip_presence_init(const pjsip_presence_cb *cb);
-
-
-/**
- * Create to presence subscription of a presentity URL.
- *
- * @param endpt Endpoint instance.
- * @param local_url Local URL.
- * @param remote_url Remote URL which the presence is being subscribed.
- * @param expires The expiration.
- * @param user_data User data to attach to presence subscription.
- *
- * @return The presence structure if successfull, or NULL if
- * failed.
- */
-PJ_DECL(pjsip_presentity*) pjsip_presence_create( pjsip_endpoint *endpt,
- const pj_str_t *local_url,
- const pj_str_t *remote_url,
- int expires,
- void *user_data );
-
-/**
- * Set credentials to be used by this presentity for outgoing requests.
- *
- * @param pres Presentity instance.
- * @param count Number of credentials in the array.
- * @param cred Array of credentials.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_presence_set_credentials( pjsip_presentity *pres,
- int count,
- const pjsip_cred_info cred[]);
-
-/**
- * Set route set for outgoing requests.
- *
- * @param pres Presentity instance.
- * @param route_set List of route headers.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_presence_set_route_set( pjsip_presentity *pres,
- const pjsip_route_hdr *hdr );
-
-/**
- * Send SUBSCRIBE request for the specified presentity.
- *
- * @param pres The presentity instance.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_presence_subscribe( pjsip_presentity *pres );
-
-/**
- * Ceased the presence subscription.
- *
- * @param pres The presence structure.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_presence_unsubscribe( pjsip_presentity *pres );
-
-/**
- * Notify subscriber about change in local status.
- *
- * @param pres The presence structure.
- * @param state Set the state of the subscription.
- * @param open Set the presence status (open or closed).
- *
- * @return Zero if a NOTIFY request can be sent.
- */
-PJ_DECL(pj_status_t) pjsip_presence_notify( pjsip_presentity *pres,
- pjsip_event_sub_state state,
- pj_bool_t open );
-
-/**
- * Destroy presence structure and the underlying subscription.
- *
- * @param pres The presence structure.
- *
- * @return Zero if the subscription was destroyed, or one if
- * the subscription can not be destroyed immediately
- * and will be destroyed later, or -1 if failed.
- */
-PJ_DECL(pj_status_t) pjsip_presence_destroy( pjsip_presentity *pres );
-
-
-/**
- * @}
- */
-
-PJ_END_DECL
-
-
-#endif /* __PJSIP_SIMPLE_PRESENCE_H__ */
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIMPLE_PRESENCE_H__ +#define __PJSIP_SIMPLE_PRESENCE_H__ + +/** + * @file presence.h + * @brief SIP Extension for Presence (RFC 3856) + */ +#include <pjsip_simple/event_notify.h> +#include <pjsip_simple/pidf.h> +#include <pjsip_simple/xpidf.h> + + +PJ_BEGIN_DECL + + +/** + * @defgroup PJSIP_SIMPLE_PRES SIP Extension for Presence (RFC 3856) + * @ingroup PJSIP_SIMPLE + * @{ + * + * This module contains the implementation of SIP Presence Extension as + * described in RFC 3856. It uses the SIP Event Notification framework + * (event_notify.h) and extends the framework by implementing "presence" + * event package. + */ + +/** + * Presence message body type. + */ +typedef enum pjsip_pres_type +{ + PJSIP_PRES_TYPE_PIDF, + PJSIP_PRES_TYPE_XPIDF, +} pjsip_pres_type; + +/** + * This structure describe a presentity, for both subscriber and notifier. + */ +typedef struct pjsip_presentity +{ + pjsip_event_sub *sub; /**< Event subscribtion record. */ + pjsip_pres_type pres_type; /**< Presentity type. */ + pjsip_msg_body *uas_body; /**< Message body (UAS only). */ + union { + pjpidf_pres *pidf; + pjxpidf_pres *xpidf; + } uas_data; /**< UAS data. */ + pj_str_t timestamp; /**< Time of last update. */ + void *user_data; /**< Application data. */ +} pjsip_presentity; + + +/** + * This structure describe callback that is registered to receive notification + * from the presence module. + */ +typedef struct pjsip_presence_cb +{ + /** + * This callback is first called when the module receives incoming + * SUBSCRIBE request to determine whether application wants to accept + * the request. If it does, then on_presence_request will be called. + * + * @param rdata The received message. + * @return Application should return 2xx to accept the request, + * or failure status (>=300) to reject the request. + */ + void (*accept_presence)(pjsip_rx_data *rdata, int *status); + + /** + * This callback is called when the module receive the first presence + * subscription request. + * + * @param pres The presence descriptor. + * @param rdata The incoming request. + * @param timeout Timeout to be set for incoming request. Otherwise + * app can just leave this and accept the default. + */ + void (*on_received_request)(pjsip_presentity *pres, pjsip_rx_data *rdata, + int *timeout); + + /** + * This callback is called when the module received subscription refresh + * request. + * + * @param pres The presence descriptor. + * @param rdata The incoming request. + */ + void (*on_received_refresh)(pjsip_presentity *pres, pjsip_rx_data *rdata); + + /** + * This callback is called when the module receives incoming NOTIFY + * request. + * + * @param pres The presence descriptor. + * @param open The latest status of the presentity. + */ + void (*on_received_update)(pjsip_presentity *pres, pj_bool_t open); + + /** + * This callback is called when the subscription has terminated. + * + * @param sub The subscription instance. + * @param reason The termination reason. + */ + void (*on_terminated)(pjsip_presentity *pres, const pj_str_t *reason); + +} pjsip_presence_cb; + + +/** + * Initialize the presence module and register callback. + * + * @param cb Callback structure. + */ +PJ_DECL(void) pjsip_presence_init(const pjsip_presence_cb *cb); + + +/** + * Create to presence subscription of a presentity URL. + * + * @param endpt Endpoint instance. + * @param local_url Local URL. + * @param remote_url Remote URL which the presence is being subscribed. + * @param expires The expiration. + * @param user_data User data to attach to presence subscription. + * + * @return The presence structure if successfull, or NULL if + * failed. + */ +PJ_DECL(pjsip_presentity*) pjsip_presence_create( pjsip_endpoint *endpt, + const pj_str_t *local_url, + const pj_str_t *remote_url, + int expires, + void *user_data ); + +/** + * Set credentials to be used by this presentity for outgoing requests. + * + * @param pres Presentity instance. + * @param count Number of credentials in the array. + * @param cred Array of credentials. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_presence_set_credentials( pjsip_presentity *pres, + int count, + const pjsip_cred_info cred[]); + +/** + * Set route set for outgoing requests. + * + * @param pres Presentity instance. + * @param route_set List of route headers. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_presence_set_route_set( pjsip_presentity *pres, + const pjsip_route_hdr *hdr ); + +/** + * Send SUBSCRIBE request for the specified presentity. + * + * @param pres The presentity instance. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_presence_subscribe( pjsip_presentity *pres ); + +/** + * Ceased the presence subscription. + * + * @param pres The presence structure. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_presence_unsubscribe( pjsip_presentity *pres ); + +/** + * Notify subscriber about change in local status. + * + * @param pres The presence structure. + * @param state Set the state of the subscription. + * @param open Set the presence status (open or closed). + * + * @return Zero if a NOTIFY request can be sent. + */ +PJ_DECL(pj_status_t) pjsip_presence_notify( pjsip_presentity *pres, + pjsip_event_sub_state state, + pj_bool_t open ); + +/** + * Destroy presence structure and the underlying subscription. + * + * @param pres The presence structure. + * + * @return Zero if the subscription was destroyed, or one if + * the subscription can not be destroyed immediately + * and will be destroyed later, or -1 if failed. + */ +PJ_DECL(pj_status_t) pjsip_presence_destroy( pjsip_presentity *pres ); + + +/** + * @} + */ + +PJ_END_DECL + + +#endif /* __PJSIP_SIMPLE_PRESENCE_H__ */ diff --git a/pjsip/include/pjsip-simple/xpidf.h b/pjsip/include/pjsip-simple/xpidf.h index a94a4f92..59d3c398 100644 --- a/pjsip/include/pjsip-simple/xpidf.h +++ b/pjsip/include/pjsip-simple/xpidf.h @@ -1,133 +1,133 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIMPLE_XPIDF_H__
-#define __PJSIP_SIMPLE_XPIDF_H__
-
-/**
- * @file xpidf.h
- * @brief XPIDF/Presence Information Data Format
- */
-#include <pj/types.h>
-#include <pj/xml.h>
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJSIP_SIMPLE_XPIDF XPIDF/Presence Information Data Format
- * @ingroup PJSIP_SIMPLE
- * @{
- *
- * This is an old presence data format as described in:
- * draft-rosenberg-impp-pidf-00.txt.
- *
- * We won't support this format extensively here, as it seems there's not
- * too many implementations support this anymore, as it shouldn't.
- */
-
-/** Type definitions for XPIDF root document. */
-typedef pj_xml_node pjxpidf_pres;
-
-
-/**
- * Create a new XPIDF document.
- *
- * @param pool Pool.
- * @param uri URI to set in the XPIDF document.
- *
- * @return XPIDF document.
- */
-PJ_DECL(pjxpidf_pres*) pjxpidf_create(pj_pool_t *pool, const pj_str_t *uri);
-
-
-/**
- * Parse XPIDF document.
- *
- * @param pool Pool.
- * @param text Input text.
- * @param len Length of input text.
- *
- * @return XPIDF document.
- */
-PJ_DECL(pjxpidf_pres*) pjxpidf_parse(pj_pool_t *pool, char *text, pj_size_t len);
-
-
-/**
- * Print XPIDF document.
- *
- * @param pres The XPIDF document to print.
- * @param text Buffer to place the output.
- * @param len Length of the buffer.
- *
- * @return The length printed.
- */
-PJ_DECL(int) pjxpidf_print( pjxpidf_pres *pres, char *text, pj_size_t len);
-
-
-/**
- * Get URI in the XPIDF document
- *
- * @param pres XPIDF document
- *
- * @return The URI, or an empty string.
- */
-PJ_DECL(pj_str_t*) pjxpidf_get_uri(pjxpidf_pres *pres);
-
-
-/**
- * Set the URI of the XPIDF document.
- *
- * @param pool Pool.
- * @param pres The XPIDF document.
- * @param uri URI to set in the XPIDF document.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pjxpidf_set_uri(pj_pool_t *pool, pjxpidf_pres *pres,
- const pj_str_t *uri);
-
-
-/**
- * Get presence status in the XPIDF document.
- *
- * @param pres XPIDF document.
- *
- * @return True to indicate the contact is online.
- */
-PJ_DECL(pj_bool_t) pjxpidf_get_status(pjxpidf_pres *pres);
-
-
-/**
- * Set presence status in the XPIDF document.
- *
- * @param pres XPIDF document.
- * @param status Status to set, True for online, False for offline.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pjxpidf_set_status(pjxpidf_pres *pres, pj_bool_t status);
-
-
-/**
- * @}
- */
-
-PJ_END_DECL
-
-
-#endif /* __PJSIP_SIMPLE_XPIDF_H__ */
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIMPLE_XPIDF_H__ +#define __PJSIP_SIMPLE_XPIDF_H__ + +/** + * @file xpidf.h + * @brief XPIDF/Presence Information Data Format + */ +#include <pj/types.h> +#include <pj/xml.h> + +PJ_BEGIN_DECL + +/** + * @defgroup PJSIP_SIMPLE_XPIDF XPIDF/Presence Information Data Format + * @ingroup PJSIP_SIMPLE + * @{ + * + * This is an old presence data format as described in: + * draft-rosenberg-impp-pidf-00.txt. + * + * We won't support this format extensively here, as it seems there's not + * too many implementations support this anymore, as it shouldn't. + */ + +/** Type definitions for XPIDF root document. */ +typedef pj_xml_node pjxpidf_pres; + + +/** + * Create a new XPIDF document. + * + * @param pool Pool. + * @param uri URI to set in the XPIDF document. + * + * @return XPIDF document. + */ +PJ_DECL(pjxpidf_pres*) pjxpidf_create(pj_pool_t *pool, const pj_str_t *uri); + + +/** + * Parse XPIDF document. + * + * @param pool Pool. + * @param text Input text. + * @param len Length of input text. + * + * @return XPIDF document. + */ +PJ_DECL(pjxpidf_pres*) pjxpidf_parse(pj_pool_t *pool, char *text, pj_size_t len); + + +/** + * Print XPIDF document. + * + * @param pres The XPIDF document to print. + * @param text Buffer to place the output. + * @param len Length of the buffer. + * + * @return The length printed. + */ +PJ_DECL(int) pjxpidf_print( pjxpidf_pres *pres, char *text, pj_size_t len); + + +/** + * Get URI in the XPIDF document + * + * @param pres XPIDF document + * + * @return The URI, or an empty string. + */ +PJ_DECL(pj_str_t*) pjxpidf_get_uri(pjxpidf_pres *pres); + + +/** + * Set the URI of the XPIDF document. + * + * @param pool Pool. + * @param pres The XPIDF document. + * @param uri URI to set in the XPIDF document. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjxpidf_set_uri(pj_pool_t *pool, pjxpidf_pres *pres, + const pj_str_t *uri); + + +/** + * Get presence status in the XPIDF document. + * + * @param pres XPIDF document. + * + * @return True to indicate the contact is online. + */ +PJ_DECL(pj_bool_t) pjxpidf_get_status(pjxpidf_pres *pres); + + +/** + * Set presence status in the XPIDF document. + * + * @param pres XPIDF document. + * @param status Status to set, True for online, False for offline. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjxpidf_set_status(pjxpidf_pres *pres, pj_bool_t status); + + +/** + * @} + */ + +PJ_END_DECL + + +#endif /* __PJSIP_SIMPLE_XPIDF_H__ */ diff --git a/pjsip/include/pjsip-ua/sip_dialog.h b/pjsip/include/pjsip-ua/sip_dialog.h index b02ddb35..d46e3873 100644 --- a/pjsip/include/pjsip-ua/sip_dialog.h +++ b/pjsip/include/pjsip-ua/sip_dialog.h @@ -1,635 +1,635 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_DIALOG_H__
-#define __PJSIP_DIALOG_H__
-
-/**
- * @file dialog.h
- * @brief SIP Dialog abstraction
- */
-
-#include <pjsip/sip_msg.h>
-#include <pjsip/sip_auth.h>
-#include <pj/sock.h>
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJSUA_DIALOG SIP Dialog
- * @ingroup PJSUA
- * @{
- * \brief
- * This file contains SIP dialog, a higher level abstraction of SIP session.
- *
- * \par Overview
- * A SIP dialog is an abstraction of communication session between two user
- * agents that persist for some time. The dialog facilitates sequencing of
- * messages between the user agents and proper routing of requests between both
- * of them. The dialog represents a context in which to interpret SIP messages.
- * However method independent User Agent processing for requests and responses
- * outside of a dialog exists, hence a dialog is not necessary for message
- * processing.
- *
- * A dialog is identified at each User Agent with a dialog Id, which consists
- * of a Call-Id value, a local tag and a remote tag.
- *
- * A dialog contains certain pieces of data needed for further message
- * transmissions within the dialog. This data consists of:
- * - Dialog Id - used to identify the dialog.
- * - Local sequence number - used to order requests from the UA to its peer.
- * - Remote sequence number - used to order requests from its peer to the UA.
- * - Local URI - the address of the local party.
- * - Remote URI - the address of the remote party.
- * - Remote target - the address from the Contact header field of the request
- * or response or refresh request or response.
- * - "secure" boolean - determines if the dialog is secure.
- * - Route set - an ordered list of URIs. The route set is the list of servers
- * that need to be traversed to send a request to the peer.
- * - Authentication info - array of authentication credentials to be used
- * by the dialog to authenticate to proxies and servers.
- *
- * \par Manipulating Dialog
- * Application should use functions declared in this file to do something with
- * the dialog. Among other things, application can:
- * - create outgoing dialog (#pjsip_dlg_init()).
- * - sends outgoing invitation (#pjsip_dlg_invite()).
- * - sends response (provisional and final) to incoming invitation
- * (#pjsip_dlg_answer())
- * - disconnect dialog (#pjsip_dlg_disconnect()).
- * - send other request (#pjsip_dlg_create_request() and #pjsip_dlg_send_msg())
- *
- * \par Getting Dialog's Notification
- * Dialog emits notification about various things that's happening to it (e.g.
- * a message is received, dialog state has changed, etc.). Normally it is in
- * the interest of the application to capture these notifications, by
- * supplying the function to be called when the event occurs in #pjsip_dlg_callback
- * structure, and register this structure to user agent by calling
- * #pjsip_ua_set_dialog_callback().
- *
- * \par Incoming Invitation
- * Upon receiving a new incoming invitation, user agent will automatically create
- * a new dialog, and inform application via \b pjsip_dlg_callback.
- */
-
-/** Forward declaration for user agent structure. */
-typedef struct pjsip_user_agent pjsip_user_agent;
-
-/** Forward declaration for dialog structure. */
-typedef struct pjsip_dlg pjsip_dlg;
-
-/**
- * \brief Type of events that are reported by the dialog to the application callback
- * function.
- */
-typedef enum pjsip_dlg_event_e
-{
- /** Dialog state has changed. */
- PJSIP_DIALOG_EVENT_STATE_CHANGED,
-
- /** Any mid-call messages (reinvitation, message, etc.). */
- PJSIP_DIALOG_EVENT_MID_CALL_REQUEST,
-
- /** Other events (low level events). */
- PJSIP_DIALOG_EVENT_OTHER,
-
-} pjsip_dlg_event_e;
-
-
-/**
- * \brief Structure registered by applications to receive dialog notifications
- * from the User Agent.
- *
- * Applications registers this structure to get notifications from the User Agent
- * about dialog state changes and other events. Application can set any of
- * the callback function to NULL if it doesn't want to handle the notification,
- * however, setting some callbacks to NULL probably will cause some undesired
- * result (such as setting \b on_incoming to NULL will cause the creation of
- * a lot of dialogs with no owner).
- */
-struct pjsip_dlg_callback
-{
- /**
- * This is a low level, uninterpreted callback that is called by framework
- * for all kinds of events, such as transaction events, dialog events, etc.
- * @param dlg The dialog.
- * @param dlg_event The type of dialog event.
- * @param event The event descriptor.
- */
- void (*on_all_events)(pjsip_dlg *dlg, pjsip_dlg_event_e dlg_event,
- pjsip_event *event );
-
- /**
- * This is a low level callback that is called by the framework when the
- * underlying transaction is about to send outgoing message. This callback
- * is provided to allow application to modify the message before it is
- * transmitted.
- * @param dlg The dialog.
- * @param tsx The transaction that transmits the message.
- * @param tdata The transmission data, which contains the message.
- * @param retransmission The number of times this message has been sent.
- * Zero indicates the message is about to be sent the first time,
- * one indicates this is the first retransmission, etc.
- */
- void (*on_before_tx)(pjsip_dlg *dlg, pjsip_transaction *tsx,
- pjsip_tx_data *tdata, pj_bool_t retransmission);
-
- /**
- * This is a low level callback that is called by the framework when the dialog
- * has sent a message. Note that a receive of retransmission will not trigger
- * this callback since retransmission is handled internally by transaction.
- * @param dlg The dialog.
- * @param tsx The transaction that transmits the message.
- * @param tdata The transmission data, which contains the message.
- */
- void (*on_tx_msg)(pjsip_dlg *dlg, pjsip_transaction *tsx,
- pjsip_tx_data *tdata);
-
- /**
- * This is a low level callback that is called by the framework when the
- * dialog has received a message. Note that a receipt of retransmission
- * will not trigger this callback since retransmission is handled internally
- * by transaction.
- * @param dlg The dialog.
- * @param tsx The transaction that receives the message.
- * @param rdata The receive data, which contains the message.
- */
- void (*on_rx_msg)(pjsip_dlg *dlg, pjsip_transaction *tsx,
- pjsip_rx_data *rdata);
-
- /**
- * This callback is called by the framework when the user agent
- * instance receives an incoming INVITE message.
- * @param dlg The new dialog that's just created to handle the incoming call.
- * @param tsx The INVITE transaction that's just created.
- * @param rdata The receive data, which contains the INVITE message.
- */
- void (*on_incoming)(pjsip_dlg *dlg, pjsip_transaction *tsx,
- pjsip_rx_data *rdata);
-
- /**
- * This callback is called by the framework when the dialog is sending
- * the first outgoing INVITE message.
- * @param dlg The dialog.
- * @param tsx The INVITE transaction.
- * @param tdata The transmit data, which contains the INVITE message.
- */
- void (*on_calling)(pjsip_dlg *dlg, pjsip_transaction *tsx,
- pjsip_tx_data *tdata);
-
- /**
- * This callback is called by the framework when the initial INVITE
- * transaction has sent/received provisional response.
- * @param dlg The dialog.
- * @param tsx The transaction.
- * @param event The event, which src_type will always be either
- * PJSIP_EVENT_RX_MSG or PJSIP_EVENT_TX_MSG. The provisional
- * response message itself will be in either \b rdata or \b tdata.
- * @see pjsip_event.
- */
- void (*on_provisional)(pjsip_dlg *dlg, pjsip_transaction *tsx,
- pjsip_event *event);
-
- /**
- * This callback is called for both UAS and UAC dialog when 200 response
- * to INVITE is sent or received.
- * @param dlg The dialog.
- * @param event The event, which src_type can only be either
- * PJSIP_EVENT_TX_MSG or PJSIP_EVENT_RX_MSG.
- * @see pjsip_event
- */
- void (*on_connecting)(pjsip_dlg *dlg, pjsip_event *event);
-
- /**
- * This callback is called for both UAS and UAC when an ACK request is
- * sent or received by the dialog.
- * @param dlg The dialog.
- * @param event The event, which src_type can only be either
- * PJSIP_EVENT_TX_MSG or PJSIP_EVENT_RX_MSG.
- * @see pjsip_event
- */
- void (*on_established)(pjsip_dlg *dlg, pjsip_event *event);
-
- /**
- * This callback is called when the dialog is disconnected, i.e. upon
- * sending/receiving non-200 response to INVITE, sending/receiving
- * CANCEL to initial INVITE, and sending/receiving BYE.
- *
- * @param dlg The dialog.
- * @param event The event.
- * @see pjsip_event
- */
- void (*on_disconnected)(pjsip_dlg *dlg, pjsip_event *event);
-
- /**
- * This callback is called when the dialog is about to be destroyed.
- * @param dlg The dialog.
- */
- void (*on_terminated)(pjsip_dlg *dlg);
-
- /**
- * This callback will be called when the dialog receives mid call events
- * such as re-invitation or incoming pager.
- *
- * @param dlg The dialog.
- * @param event The event.
- */
- void (*on_mid_call_events)(pjsip_dlg *dlg, pjsip_event *event);
-
-}; /* struct pjsip_dlg_callback */
-
-
-
-/**
- * Dialog state.
- */
-typedef enum pjsip_dlg_state_e
-{
- /**
- * State NULL is after the dialog is instantiated but before any
- * initialization is done.
- */
- PJSIP_DIALOG_STATE_NULL,
-
- /**
- * State INCOMING is after the (callee) dialog has been initialized with
- * the incoming request, but before any responses is sent by the dialog.
- */
- PJSIP_DIALOG_STATE_INCOMING,
-
- /**
- * State CALLING is after the (caller) dialog has sent outgoing invitation
- * but before any responses are received.
- */
- PJSIP_DIALOG_STATE_CALLING,
-
- /**
- * State PROCEEDING is after the dialog sent/received provisional
- * responses, but before final response is sent/received.
- */
- PJSIP_DIALOG_STATE_PROCEEDING,
-
- /**
- * State CONNECTING is after the dialog has sent/received final response
- * to the invitation, but before acknowledgement is sent.
- */
- PJSIP_DIALOG_STATE_CONNECTING,
-
- /**
- * State ESTABLISHED occurs after the invitation has been accepted and
- * acknowledged.
- */
- PJSIP_DIALOG_STATE_ESTABLISHED,
-
- /**
- * State DISCONNECTED occurs after either party successfully disconnect
- * the session.
- */
- PJSIP_DIALOG_STATE_DISCONNECTED,
-
- /**
- * State TERMINATE occurs when the dialog is ready to be destroyed.
- */
- PJSIP_DIALOG_STATE_TERMINATED,
-
-} pjsip_dlg_state_e;
-
-
-/**
- * Get the dialog string state.
- *
- * @param state Dialog state.
- * @return The string describing the state.
- */
-const char *pjsip_dlg_state_str(pjsip_dlg_state_e state);
-
-/**
- * This structure is used to describe dialog's participants, which in this
- * case is local party (i.e. us) and remote party.
- */
-typedef struct pjsip_dlg_party
-{
- pjsip_uri *target; /**< Target URL. */
- pjsip_fromto_hdr *info; /**< URL in From/To header. */
- pj_str_t tag; /**< Tag. */
- pjsip_contact_hdr *contact; /**< URL in Contact. */
- pj_sockaddr_in addr; /**< The current transport address. */
- int cseq; /**< Sequence number counter. */
-} pjsip_dlg_party;
-
-
-/**
- * This structure describes the dialog structure.
- */
-struct pjsip_dlg
-{
- PJ_DECL_LIST_MEMBER(struct pjsip_dlg)
-
- char obj_name[PJ_MAX_OBJ_NAME]; /**< Log identification. */
-
- pjsip_user_agent *ua; /**< User agent instance. */
- pj_pool_t *pool; /**< Dialog's pool. */
- pjsip_dlg_state_e state; /**< Dialog's call state. */
- pjsip_role_e role; /**< Dialog's role. */
- pj_mutex_t *mutex; /**< Dialog's mutex. */
-
- pjsip_dlg_party local; /**< Local party info. */
- pjsip_dlg_party remote; /**< Remote party info. */
-
- pjsip_cid_hdr *call_id; /**< Call-ID */
- pj_bool_t secure; /**< Use secure transport? */
-
- pjsip_route_hdr route_set; /**< Dialog's route set. */
- pjsip_transaction *invite_tsx; /**< Current INVITE transaction. */
- int pending_tsx_count; /**< Total pending tsx count. */
-
- int cred_count; /**< Number of credentials. */
- pjsip_cred_info *cred_info; /**< Array of credentials. */
-
- pjsip_auth_session auth_sess; /**< List of auth session. */
-
- pjsip_msg_body *body;
-
- void *user_data; /**< Application's data. */
-
- int (*handle_tsx_event)(struct pjsip_dlg *, /**< Internal state handler.*/
- pjsip_transaction *,
- pjsip_event *);
-};
-
-
-/**
- * Initialize dialog with local and remote info. This function is normally
- * called after application creates the dialog with #pjsip_ua_create_dialog
- * for UAC dialogs.
- *
- * This function will initialize local and remote info from the URL, generate
- * a globally unique Call-ID, initialize CSeq, and initialize other dialog's
- * internal attributes.
- *
- * @param dlg The dialog to initialize.
- * @param local_info URI/name address to be used as local info
- * (From and Contact headers).
- * @param remote_info URI/name address to be used as remote info (To header).
- * @param target URI for initial remote's target, or NULL to set the
- * initial target the same as remote_info.
- *
- * @return zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_dlg_init( pjsip_dlg *dlg,
- const pj_str_t *local_info,
- const pj_str_t *remote_info,
- const pj_str_t *target);
-
-
-/**
- * Set authentication credentials to be used by this dialog.
- *
- * If authentication credentials are set for the dialog, the dialog will try to
- * perform authentication automatically using the credentials supplied, and
- * also cache the last Authorization or Proxy-Authorization headers for next
- * requests.
- *
- * If none of the credentials are suitable or accepted by remote, then
- * the dialog will just pass the authorization failure response back to
- * application.
- *
- * @param dlg The dialog.
- * @param count Number of credentials in the array.
- * @param cred Array of credentials.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_dlg_set_credentials( pjsip_dlg *dlg,
- int count,
- const pjsip_cred_info cred[]);
-
-/**
- * Override local contact details.
- *
- * Call this function to change the contact details to be advertised in Contact
- * header. Application normally need to call this function for incoming calls
- * before answering the call with 200/OK, because for an incoming dialogs, the
- * initial local contact info are generated from the To header, which is
- * normally not the appropriate one.
- *
- * @param dlg The dialog.
- * @param contact The contact to use.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_dlg_set_contact( pjsip_dlg *dlg,
- const pj_str_t *contact );
-
-
-/**
- * Set initial route set to be used by the dialog. This initial route set
- * governs where and how the initial INVITE request will be routed. This
- * initial route set will be overwritten with the route set found in the
- * 2xx response of INVITE.
- *
- * Application only needs to call this function if it wants to have custom
- * route for individual dialogs. If only a single route for all dialogs is
- * needed, then application can set the global route by calling function
- * #pjsip_endpt_set_proxies().
- *
- * @param dlg The dialog.
- * @param route_set The route set list.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_dlg_set_route_set( pjsip_dlg *dlg,
- const pjsip_route_hdr *route_set );
-
-
-/**
- * Variation of #pjsip_dlg_set_route_set where the headers will be used
- * as it is (i.e. without cloned).
- *
- * @param dlg The dialog.
- * @param route_set The route set list.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_dlg_set_route_set_np( pjsip_dlg *dlg,
- pjsip_route_hdr *route_set);
-
-/**
- * Create initial outgoing INVITE message.
- *
- * This function is just a simple wrapper to #pjsip_dlg_create_request(),
- * so it follows the same rule there. In addition, this function also adds
- * \b Allow header to the outgoing request.
- *
- * After the message is successfully created, application must call
- * #pjsip_dlg_send_msg() to actually send the message and update the dialog's
- * state. Note that upon return the reference counter of the transmit data
- * will be set to one.
- *
- * @param dlg The dialog.
- *
- * @return The dialog transmit data, or NULL.
- */
-PJ_DECL(pjsip_tx_data*) pjsip_dlg_invite( pjsip_dlg *dlg );
-
-
-/**
- * Answer incoming dialog invitation, with either provisional responses
- * or a final response. Application can only call this function when there's
- * a pending invitation to be answered.
- *
- * After the message is successfully created, application must call
- * #pjsip_dlg_send_msg() to actually send the message and update the dialog's
- * state. Note that upon return the reference counter of the transmit data
- * will be set to one.
- *
- * @param dlg The dialog.
- * @param code The response code, which can be:
- * - 100-199 Provisional response (application can issue multiple
- * provisional responses).
- * - 200-299 To answer the invitation (normally status code 200
- * is sent).
- * - 300-699 To reject the invitation.
- * @return Transmit data if successfull.
- */
-PJ_DECL(pjsip_tx_data*) pjsip_dlg_answer( pjsip_dlg *dlg, int code );
-
-
-/**
- * High level function to create message to disconnect dialog. Depending
- * on dialog's state, this function will either create CANCEL, final response,
- * or BYE message. A status code must be supplied, which will be set if dialog
- * will be transmitting a final response to INVITE.
- *
- * After the message is successfully created, application must call
- * #pjsip_dlg_send_msg to actually send the message and update the dialog's
- * state. Note that upon return the reference counter of the transmit data
- * will be set to one.
- *
- * @param dlg The dialog.
- * @param status_code The status code for disconnection.
- * @return Transmit data if successfull.
- */
-PJ_DECL(pjsip_tx_data*) pjsip_dlg_disconnect( pjsip_dlg *dlg, int status_code);
-
-/**
- * Create CANCEL message to cancel pending outgoing dialog invitation.
- * Normally application should call #pjsip_dlg_disconnect() instead, because
- * that function will create the correct message regardless of the state of
- * the dialog.
- *
- * Application can call this function at anytime after it issues outgoing
- * invitation and before receiving final response. However, there's no
- * guarantee that the invitation will be successfully cancelled, since the
- * CANCEL request and the final response can pass over in the wire. So the
- * application must prepare to have the dialog connected even after the
- * dialog is cancelled.
- *
- * The final state of the dialog will be reported in the dialog callback.
- * If the CANCEL request succeeded, then the dialog will be disconnected with
- * status code \a PJSIP_SC_REQUEST_TERMINATED.
- *
- * After the message is successfully created, application must call
- * #pjsip_dlg_send_msg() to actually send the message and update the dialog's
- * state.
- *
- * Upon return of this function, the reference counter of the transmit data
- * will be set to one.
- *
- * @param dlg The dialog.
- * @return The dialog transmit data containing the CANCEL message,
- * or NULL.
- */
-PJ_DECL(pjsip_tx_data*) pjsip_dlg_cancel( pjsip_dlg *dlg );
-
-
-/**
- * Create BYE message. Application shouldn't normally need to use this function,
- * but rather it's preferable to use #pjsip_dlg_disconnect() instead because
- * that function will work to disconnect the session no matter what the state
- * is.
- *
- * After the message is successfully created, application must call
- * #pjsip_dlg_send_msg() to actually send the message and update the dialog's
- * state. Note that upon return the reference counter of the transmit data
- * will be set to one.
- *
- * @param dlg The dialog.
- * @return The BYE message or NULL.
- */
-PJ_DECL(pjsip_tx_data*) pjsip_dlg_bye( pjsip_dlg *dlg );
-
-/**
- * This function is called by application to create new outgoing request
- * message for this dialog. After the request is created, application can
- * modify the message (such adding headers), and eventually send the request
- * by calling #pjsip_dlg_send_msg().
- *
- * This function will initialize the request message with dialog's properties
- * as follows:
- * - the request line is initialized with the method and the target is
- * initialized from current remote target.
- * - \b From, \b To, \b Contact, and \b Call-Id headers will be added.
- * - An initial \b CSeq header will be provided (although the value will be
- * verified again when the message is actually sent with #pjsip_dlg_send_msg().
- * - \b Route headers will be added from dialog's route set.
- * - Authentication headers (\b Authorization or \b Proxy-Authorization) will
- * be added from dialog's authorization cache.
- *
- * Note that upon return the reference counter of the transmit data
- * will be set to one. When the message is sent, #pjsip_dlg_send_msg() will
- * decrement the reference counter, and when the reference counter reach zero,
- * the message will be deleted.
- *
- * @param dlg The dialog.
- * @param method The request method.
- * @param cseq Specify CSeq, or -1 to let the dialog specify CSeq.
- *
- * @return Transmit data for the new request.
- *
- * @see pjsip_dlg_send_msg()
- */
-PJ_DECL(pjsip_tx_data*) pjsip_dlg_create_request( pjsip_dlg *dlg,
- const pjsip_method *method,
- int cseq);
-
-
-/**
- * This function can be called by application to send outgoing message (request
- * or response) to remote party. Note that after calling this function, the
- * transmit data will be deleted regardless of the return status. To prevent
- * deletion, application must increase the reference count, but then it will
- * be responsible to delete this transmit data itself (by decreasing the
- * reference count).
- *
- * @param dlg The dialog.
- * @param tdata The transmit data, which contains the request message.
- * @return zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_dlg_send_msg( pjsip_dlg *dlg,
- pjsip_tx_data *tdata );
-
-
-/**
- * @}
- */
-
-PJ_END_DECL
-
-#endif /* __PJSIP_DIALOG_H__ */
-
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_DIALOG_H__ +#define __PJSIP_DIALOG_H__ + +/** + * @file dialog.h + * @brief SIP Dialog abstraction + */ + +#include <pjsip/sip_msg.h> +#include <pjsip/sip_auth.h> +#include <pj/sock.h> + +PJ_BEGIN_DECL + +/** + * @defgroup PJSUA_DIALOG SIP Dialog + * @ingroup PJSUA + * @{ + * \brief + * This file contains SIP dialog, a higher level abstraction of SIP session. + * + * \par Overview + * A SIP dialog is an abstraction of communication session between two user + * agents that persist for some time. The dialog facilitates sequencing of + * messages between the user agents and proper routing of requests between both + * of them. The dialog represents a context in which to interpret SIP messages. + * However method independent User Agent processing for requests and responses + * outside of a dialog exists, hence a dialog is not necessary for message + * processing. + * + * A dialog is identified at each User Agent with a dialog Id, which consists + * of a Call-Id value, a local tag and a remote tag. + * + * A dialog contains certain pieces of data needed for further message + * transmissions within the dialog. This data consists of: + * - Dialog Id - used to identify the dialog. + * - Local sequence number - used to order requests from the UA to its peer. + * - Remote sequence number - used to order requests from its peer to the UA. + * - Local URI - the address of the local party. + * - Remote URI - the address of the remote party. + * - Remote target - the address from the Contact header field of the request + * or response or refresh request or response. + * - "secure" boolean - determines if the dialog is secure. + * - Route set - an ordered list of URIs. The route set is the list of servers + * that need to be traversed to send a request to the peer. + * - Authentication info - array of authentication credentials to be used + * by the dialog to authenticate to proxies and servers. + * + * \par Manipulating Dialog + * Application should use functions declared in this file to do something with + * the dialog. Among other things, application can: + * - create outgoing dialog (#pjsip_dlg_init()). + * - sends outgoing invitation (#pjsip_dlg_invite()). + * - sends response (provisional and final) to incoming invitation + * (#pjsip_dlg_answer()) + * - disconnect dialog (#pjsip_dlg_disconnect()). + * - send other request (#pjsip_dlg_create_request() and #pjsip_dlg_send_msg()) + * + * \par Getting Dialog's Notification + * Dialog emits notification about various things that's happening to it (e.g. + * a message is received, dialog state has changed, etc.). Normally it is in + * the interest of the application to capture these notifications, by + * supplying the function to be called when the event occurs in #pjsip_dlg_callback + * structure, and register this structure to user agent by calling + * #pjsip_ua_set_dialog_callback(). + * + * \par Incoming Invitation + * Upon receiving a new incoming invitation, user agent will automatically create + * a new dialog, and inform application via \b pjsip_dlg_callback. + */ + +/** Forward declaration for user agent structure. */ +typedef struct pjsip_user_agent pjsip_user_agent; + +/** Forward declaration for dialog structure. */ +typedef struct pjsip_dlg pjsip_dlg; + +/** + * \brief Type of events that are reported by the dialog to the application callback + * function. + */ +typedef enum pjsip_dlg_event_e +{ + /** Dialog state has changed. */ + PJSIP_DIALOG_EVENT_STATE_CHANGED, + + /** Any mid-call messages (reinvitation, message, etc.). */ + PJSIP_DIALOG_EVENT_MID_CALL_REQUEST, + + /** Other events (low level events). */ + PJSIP_DIALOG_EVENT_OTHER, + +} pjsip_dlg_event_e; + + +/** + * \brief Structure registered by applications to receive dialog notifications + * from the User Agent. + * + * Applications registers this structure to get notifications from the User Agent + * about dialog state changes and other events. Application can set any of + * the callback function to NULL if it doesn't want to handle the notification, + * however, setting some callbacks to NULL probably will cause some undesired + * result (such as setting \b on_incoming to NULL will cause the creation of + * a lot of dialogs with no owner). + */ +struct pjsip_dlg_callback +{ + /** + * This is a low level, uninterpreted callback that is called by framework + * for all kinds of events, such as transaction events, dialog events, etc. + * @param dlg The dialog. + * @param dlg_event The type of dialog event. + * @param event The event descriptor. + */ + void (*on_all_events)(pjsip_dlg *dlg, pjsip_dlg_event_e dlg_event, + pjsip_event *event ); + + /** + * This is a low level callback that is called by the framework when the + * underlying transaction is about to send outgoing message. This callback + * is provided to allow application to modify the message before it is + * transmitted. + * @param dlg The dialog. + * @param tsx The transaction that transmits the message. + * @param tdata The transmission data, which contains the message. + * @param retransmission The number of times this message has been sent. + * Zero indicates the message is about to be sent the first time, + * one indicates this is the first retransmission, etc. + */ + void (*on_before_tx)(pjsip_dlg *dlg, pjsip_transaction *tsx, + pjsip_tx_data *tdata, pj_bool_t retransmission); + + /** + * This is a low level callback that is called by the framework when the dialog + * has sent a message. Note that a receive of retransmission will not trigger + * this callback since retransmission is handled internally by transaction. + * @param dlg The dialog. + * @param tsx The transaction that transmits the message. + * @param tdata The transmission data, which contains the message. + */ + void (*on_tx_msg)(pjsip_dlg *dlg, pjsip_transaction *tsx, + pjsip_tx_data *tdata); + + /** + * This is a low level callback that is called by the framework when the + * dialog has received a message. Note that a receipt of retransmission + * will not trigger this callback since retransmission is handled internally + * by transaction. + * @param dlg The dialog. + * @param tsx The transaction that receives the message. + * @param rdata The receive data, which contains the message. + */ + void (*on_rx_msg)(pjsip_dlg *dlg, pjsip_transaction *tsx, + pjsip_rx_data *rdata); + + /** + * This callback is called by the framework when the user agent + * instance receives an incoming INVITE message. + * @param dlg The new dialog that's just created to handle the incoming call. + * @param tsx The INVITE transaction that's just created. + * @param rdata The receive data, which contains the INVITE message. + */ + void (*on_incoming)(pjsip_dlg *dlg, pjsip_transaction *tsx, + pjsip_rx_data *rdata); + + /** + * This callback is called by the framework when the dialog is sending + * the first outgoing INVITE message. + * @param dlg The dialog. + * @param tsx The INVITE transaction. + * @param tdata The transmit data, which contains the INVITE message. + */ + void (*on_calling)(pjsip_dlg *dlg, pjsip_transaction *tsx, + pjsip_tx_data *tdata); + + /** + * This callback is called by the framework when the initial INVITE + * transaction has sent/received provisional response. + * @param dlg The dialog. + * @param tsx The transaction. + * @param event The event, which src_type will always be either + * PJSIP_EVENT_RX_MSG or PJSIP_EVENT_TX_MSG. The provisional + * response message itself will be in either \b rdata or \b tdata. + * @see pjsip_event. + */ + void (*on_provisional)(pjsip_dlg *dlg, pjsip_transaction *tsx, + pjsip_event *event); + + /** + * This callback is called for both UAS and UAC dialog when 200 response + * to INVITE is sent or received. + * @param dlg The dialog. + * @param event The event, which src_type can only be either + * PJSIP_EVENT_TX_MSG or PJSIP_EVENT_RX_MSG. + * @see pjsip_event + */ + void (*on_connecting)(pjsip_dlg *dlg, pjsip_event *event); + + /** + * This callback is called for both UAS and UAC when an ACK request is + * sent or received by the dialog. + * @param dlg The dialog. + * @param event The event, which src_type can only be either + * PJSIP_EVENT_TX_MSG or PJSIP_EVENT_RX_MSG. + * @see pjsip_event + */ + void (*on_established)(pjsip_dlg *dlg, pjsip_event *event); + + /** + * This callback is called when the dialog is disconnected, i.e. upon + * sending/receiving non-200 response to INVITE, sending/receiving + * CANCEL to initial INVITE, and sending/receiving BYE. + * + * @param dlg The dialog. + * @param event The event. + * @see pjsip_event + */ + void (*on_disconnected)(pjsip_dlg *dlg, pjsip_event *event); + + /** + * This callback is called when the dialog is about to be destroyed. + * @param dlg The dialog. + */ + void (*on_terminated)(pjsip_dlg *dlg); + + /** + * This callback will be called when the dialog receives mid call events + * such as re-invitation or incoming pager. + * + * @param dlg The dialog. + * @param event The event. + */ + void (*on_mid_call_events)(pjsip_dlg *dlg, pjsip_event *event); + +}; /* struct pjsip_dlg_callback */ + + + +/** + * Dialog state. + */ +typedef enum pjsip_dlg_state_e +{ + /** + * State NULL is after the dialog is instantiated but before any + * initialization is done. + */ + PJSIP_DIALOG_STATE_NULL, + + /** + * State INCOMING is after the (callee) dialog has been initialized with + * the incoming request, but before any responses is sent by the dialog. + */ + PJSIP_DIALOG_STATE_INCOMING, + + /** + * State CALLING is after the (caller) dialog has sent outgoing invitation + * but before any responses are received. + */ + PJSIP_DIALOG_STATE_CALLING, + + /** + * State PROCEEDING is after the dialog sent/received provisional + * responses, but before final response is sent/received. + */ + PJSIP_DIALOG_STATE_PROCEEDING, + + /** + * State CONNECTING is after the dialog has sent/received final response + * to the invitation, but before acknowledgement is sent. + */ + PJSIP_DIALOG_STATE_CONNECTING, + + /** + * State ESTABLISHED occurs after the invitation has been accepted and + * acknowledged. + */ + PJSIP_DIALOG_STATE_ESTABLISHED, + + /** + * State DISCONNECTED occurs after either party successfully disconnect + * the session. + */ + PJSIP_DIALOG_STATE_DISCONNECTED, + + /** + * State TERMINATE occurs when the dialog is ready to be destroyed. + */ + PJSIP_DIALOG_STATE_TERMINATED, + +} pjsip_dlg_state_e; + + +/** + * Get the dialog string state. + * + * @param state Dialog state. + * @return The string describing the state. + */ +const char *pjsip_dlg_state_str(pjsip_dlg_state_e state); + +/** + * This structure is used to describe dialog's participants, which in this + * case is local party (i.e. us) and remote party. + */ +typedef struct pjsip_dlg_party +{ + pjsip_uri *target; /**< Target URL. */ + pjsip_fromto_hdr *info; /**< URL in From/To header. */ + pj_str_t tag; /**< Tag. */ + pjsip_contact_hdr *contact; /**< URL in Contact. */ + pj_sockaddr_in addr; /**< The current transport address. */ + int cseq; /**< Sequence number counter. */ +} pjsip_dlg_party; + + +/** + * This structure describes the dialog structure. + */ +struct pjsip_dlg +{ + PJ_DECL_LIST_MEMBER(struct pjsip_dlg) + + char obj_name[PJ_MAX_OBJ_NAME]; /**< Log identification. */ + + pjsip_user_agent *ua; /**< User agent instance. */ + pj_pool_t *pool; /**< Dialog's pool. */ + pjsip_dlg_state_e state; /**< Dialog's call state. */ + pjsip_role_e role; /**< Dialog's role. */ + pj_mutex_t *mutex; /**< Dialog's mutex. */ + + pjsip_dlg_party local; /**< Local party info. */ + pjsip_dlg_party remote; /**< Remote party info. */ + + pjsip_cid_hdr *call_id; /**< Call-ID */ + pj_bool_t secure; /**< Use secure transport? */ + + pjsip_route_hdr route_set; /**< Dialog's route set. */ + pjsip_transaction *invite_tsx; /**< Current INVITE transaction. */ + int pending_tsx_count; /**< Total pending tsx count. */ + + int cred_count; /**< Number of credentials. */ + pjsip_cred_info *cred_info; /**< Array of credentials. */ + + pjsip_auth_session auth_sess; /**< List of auth session. */ + + pjsip_msg_body *body; + + void *user_data; /**< Application's data. */ + + int (*handle_tsx_event)(struct pjsip_dlg *, /**< Internal state handler.*/ + pjsip_transaction *, + pjsip_event *); +}; + + +/** + * Initialize dialog with local and remote info. This function is normally + * called after application creates the dialog with #pjsip_ua_create_dialog + * for UAC dialogs. + * + * This function will initialize local and remote info from the URL, generate + * a globally unique Call-ID, initialize CSeq, and initialize other dialog's + * internal attributes. + * + * @param dlg The dialog to initialize. + * @param local_info URI/name address to be used as local info + * (From and Contact headers). + * @param remote_info URI/name address to be used as remote info (To header). + * @param target URI for initial remote's target, or NULL to set the + * initial target the same as remote_info. + * + * @return zero on success. + */ +PJ_DECL(pj_status_t) pjsip_dlg_init( pjsip_dlg *dlg, + const pj_str_t *local_info, + const pj_str_t *remote_info, + const pj_str_t *target); + + +/** + * Set authentication credentials to be used by this dialog. + * + * If authentication credentials are set for the dialog, the dialog will try to + * perform authentication automatically using the credentials supplied, and + * also cache the last Authorization or Proxy-Authorization headers for next + * requests. + * + * If none of the credentials are suitable or accepted by remote, then + * the dialog will just pass the authorization failure response back to + * application. + * + * @param dlg The dialog. + * @param count Number of credentials in the array. + * @param cred Array of credentials. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_dlg_set_credentials( pjsip_dlg *dlg, + int count, + const pjsip_cred_info cred[]); + +/** + * Override local contact details. + * + * Call this function to change the contact details to be advertised in Contact + * header. Application normally need to call this function for incoming calls + * before answering the call with 200/OK, because for an incoming dialogs, the + * initial local contact info are generated from the To header, which is + * normally not the appropriate one. + * + * @param dlg The dialog. + * @param contact The contact to use. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_dlg_set_contact( pjsip_dlg *dlg, + const pj_str_t *contact ); + + +/** + * Set initial route set to be used by the dialog. This initial route set + * governs where and how the initial INVITE request will be routed. This + * initial route set will be overwritten with the route set found in the + * 2xx response of INVITE. + * + * Application only needs to call this function if it wants to have custom + * route for individual dialogs. If only a single route for all dialogs is + * needed, then application can set the global route by calling function + * #pjsip_endpt_set_proxies(). + * + * @param dlg The dialog. + * @param route_set The route set list. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_dlg_set_route_set( pjsip_dlg *dlg, + const pjsip_route_hdr *route_set ); + + +/** + * Variation of #pjsip_dlg_set_route_set where the headers will be used + * as it is (i.e. without cloned). + * + * @param dlg The dialog. + * @param route_set The route set list. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_dlg_set_route_set_np( pjsip_dlg *dlg, + pjsip_route_hdr *route_set); + +/** + * Create initial outgoing INVITE message. + * + * This function is just a simple wrapper to #pjsip_dlg_create_request(), + * so it follows the same rule there. In addition, this function also adds + * \b Allow header to the outgoing request. + * + * After the message is successfully created, application must call + * #pjsip_dlg_send_msg() to actually send the message and update the dialog's + * state. Note that upon return the reference counter of the transmit data + * will be set to one. + * + * @param dlg The dialog. + * + * @return The dialog transmit data, or NULL. + */ +PJ_DECL(pjsip_tx_data*) pjsip_dlg_invite( pjsip_dlg *dlg ); + + +/** + * Answer incoming dialog invitation, with either provisional responses + * or a final response. Application can only call this function when there's + * a pending invitation to be answered. + * + * After the message is successfully created, application must call + * #pjsip_dlg_send_msg() to actually send the message and update the dialog's + * state. Note that upon return the reference counter of the transmit data + * will be set to one. + * + * @param dlg The dialog. + * @param code The response code, which can be: + * - 100-199 Provisional response (application can issue multiple + * provisional responses). + * - 200-299 To answer the invitation (normally status code 200 + * is sent). + * - 300-699 To reject the invitation. + * @return Transmit data if successfull. + */ +PJ_DECL(pjsip_tx_data*) pjsip_dlg_answer( pjsip_dlg *dlg, int code ); + + +/** + * High level function to create message to disconnect dialog. Depending + * on dialog's state, this function will either create CANCEL, final response, + * or BYE message. A status code must be supplied, which will be set if dialog + * will be transmitting a final response to INVITE. + * + * After the message is successfully created, application must call + * #pjsip_dlg_send_msg to actually send the message and update the dialog's + * state. Note that upon return the reference counter of the transmit data + * will be set to one. + * + * @param dlg The dialog. + * @param status_code The status code for disconnection. + * @return Transmit data if successfull. + */ +PJ_DECL(pjsip_tx_data*) pjsip_dlg_disconnect( pjsip_dlg *dlg, int status_code); + +/** + * Create CANCEL message to cancel pending outgoing dialog invitation. + * Normally application should call #pjsip_dlg_disconnect() instead, because + * that function will create the correct message regardless of the state of + * the dialog. + * + * Application can call this function at anytime after it issues outgoing + * invitation and before receiving final response. However, there's no + * guarantee that the invitation will be successfully cancelled, since the + * CANCEL request and the final response can pass over in the wire. So the + * application must prepare to have the dialog connected even after the + * dialog is cancelled. + * + * The final state of the dialog will be reported in the dialog callback. + * If the CANCEL request succeeded, then the dialog will be disconnected with + * status code \a PJSIP_SC_REQUEST_TERMINATED. + * + * After the message is successfully created, application must call + * #pjsip_dlg_send_msg() to actually send the message and update the dialog's + * state. + * + * Upon return of this function, the reference counter of the transmit data + * will be set to one. + * + * @param dlg The dialog. + * @return The dialog transmit data containing the CANCEL message, + * or NULL. + */ +PJ_DECL(pjsip_tx_data*) pjsip_dlg_cancel( pjsip_dlg *dlg ); + + +/** + * Create BYE message. Application shouldn't normally need to use this function, + * but rather it's preferable to use #pjsip_dlg_disconnect() instead because + * that function will work to disconnect the session no matter what the state + * is. + * + * After the message is successfully created, application must call + * #pjsip_dlg_send_msg() to actually send the message and update the dialog's + * state. Note that upon return the reference counter of the transmit data + * will be set to one. + * + * @param dlg The dialog. + * @return The BYE message or NULL. + */ +PJ_DECL(pjsip_tx_data*) pjsip_dlg_bye( pjsip_dlg *dlg ); + +/** + * This function is called by application to create new outgoing request + * message for this dialog. After the request is created, application can + * modify the message (such adding headers), and eventually send the request + * by calling #pjsip_dlg_send_msg(). + * + * This function will initialize the request message with dialog's properties + * as follows: + * - the request line is initialized with the method and the target is + * initialized from current remote target. + * - \b From, \b To, \b Contact, and \b Call-Id headers will be added. + * - An initial \b CSeq header will be provided (although the value will be + * verified again when the message is actually sent with #pjsip_dlg_send_msg(). + * - \b Route headers will be added from dialog's route set. + * - Authentication headers (\b Authorization or \b Proxy-Authorization) will + * be added from dialog's authorization cache. + * + * Note that upon return the reference counter of the transmit data + * will be set to one. When the message is sent, #pjsip_dlg_send_msg() will + * decrement the reference counter, and when the reference counter reach zero, + * the message will be deleted. + * + * @param dlg The dialog. + * @param method The request method. + * @param cseq Specify CSeq, or -1 to let the dialog specify CSeq. + * + * @return Transmit data for the new request. + * + * @see pjsip_dlg_send_msg() + */ +PJ_DECL(pjsip_tx_data*) pjsip_dlg_create_request( pjsip_dlg *dlg, + const pjsip_method *method, + int cseq); + + +/** + * This function can be called by application to send outgoing message (request + * or response) to remote party. Note that after calling this function, the + * transmit data will be deleted regardless of the return status. To prevent + * deletion, application must increase the reference count, but then it will + * be responsible to delete this transmit data itself (by decreasing the + * reference count). + * + * @param dlg The dialog. + * @param tdata The transmit data, which contains the request message. + * @return zero on success. + */ +PJ_DECL(pj_status_t) pjsip_dlg_send_msg( pjsip_dlg *dlg, + pjsip_tx_data *tdata ); + + +/** + * @} + */ + +PJ_END_DECL + +#endif /* __PJSIP_DIALOG_H__ */ + diff --git a/pjsip/include/pjsip-ua/sip_regc.h b/pjsip/include/pjsip-ua/sip_regc.h index b9752dc1..5a4e2ebe 100644 --- a/pjsip/include/pjsip-ua/sip_regc.h +++ b/pjsip/include/pjsip-ua/sip_regc.h @@ -1,210 +1,210 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIP_REG_H__
-#define __PJSIP_SIP_REG_H__
-
-/**
- * @file sip_reg.h
- * @brief SIP Registration Client
- */
-
-#include <pjsip/sip_types.h>
-#include <pjsip/sip_auth.h>
-#include <pjsip_mod_ua/sip_ua.h>
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJSUA_REGC SIP Registration Client
- * @ingroup PJSUA
- * @{
- * \brief
- * API for performing registration for user agent.
- */
-
-/** Typedef for client registration data. */
-typedef struct pjsip_regc pjsip_regc;
-
-/** Maximum contacts in registration. */
-#define PJSIP_REGC_MAX_CONTACT 10
-
-/** Expiration not specified. */
-#define PJSIP_REGC_EXPIRATION_NOT_SPECIFIED ((pj_uint32_t)0xFFFFFFFFUL)
-
-/** Buffer to hold all contacts. */
-#define PJSIP_REGC_CONTACT_BUF_SIZE 512
-
-/** Structure to hold parameters when calling application's callback.
- * The application's callback is called when the client registration process
- * has finished.
- */
-struct pjsip_regc_cbparam
-{
- pjsip_regc *regc;
- void *token;
- int code;
- pj_str_t reason;
- pjsip_rx_data *rdata;
- int contact_cnt;
- int expiration;
- pjsip_contact_hdr *contact[PJSIP_REGC_MAX_CONTACT];
-};
-
-
-/** Type declaration for callback to receive registration result. */
-typedef void pjsip_regc_cb(struct pjsip_regc_cbparam *param);
-
-
-/**
- * Get the module instance for client registration module.
- *
- * @return client registration module.
- */
-PJ_DECL(pjsip_module*) pjsip_regc_get_module(void);
-
-
-/**
- * Create client registration structure.
- *
- * @param endpt Endpoint, used to allocate pool from.
- * @param token A data to be associated with the client registration struct.
- * @param cb Pointer to callback function to receive registration status.
- *
- * @return client registration structure.
- */
-PJ_DECL(pjsip_regc*) pjsip_regc_create( pjsip_endpoint *endpt, void *token,
- pjsip_regc_cb *cb);
-
-
-/**
- * Destroy client registration structure. If a registration transaction is
- * in progress, then the structure will be deleted only after a final response
- * has been received, and in this case, the callback won't be called.
- *
- * @param regc The client registration structure.
- */
-PJ_DECL(void) pjsip_regc_destroy(pjsip_regc *regc);
-
-/**
- * Get the memory pool associated with a registration client handle.
- *
- * @param regc The client registration structure.
- * @return pool handle.
- */
-PJ_DECL(pj_pool_t*) pjsip_regc_get_pool(pjsip_regc *regc);
-
-/**
- * Initialize client registration structure with various information needed to
- * perform the registration.
- *
- * @param regc The client registration structure.
- * @param from_url The person performing the registration, must be a SIP URL type.
- * @param to_url The address of record for which the registration is targetd, must
- * be a SIP/SIPS URL.
- * @param ccnt Number of contacts in the array.
- * @param contact Array of contacts.
- * @param expires Default expiration interval (in seconds) to be applied for
- * contact URL that doesn't have expiration settings. If the
- * value PJSIP_REGC_EXPIRATION_NOT_SPECIFIED is given, then
- * no default expiration will be applied.
- * @return zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_regc_init(pjsip_regc *regc,
- const pj_str_t *srv_url,
- const pj_str_t *from_url,
- const pj_str_t *to_url,
- int ccnt,
- const pj_str_t contact[],
- pj_uint32_t expires);
-
-
-/**
- * Set authentication credentials to use by this registration.
- *
- * @param dlg The registration structure.
- * @param count Number of credentials in the array.
- * @param cred Array of credentials.
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_regc_set_credentials( pjsip_regc *regc,
- int count,
- const pjsip_cred_info cred[] );
-
-/**
- * Create REGISTER request for the specified client registration structure.
- *
- * After successfull registration, application can inspect the contacts in
- * the client registration structure to list what contacts are associaciated
- * with the address of record being targeted in the registration.
- *
- * @param regc The client registration structure.
- * @param autoreg If non zero, the library will automatically refresh the
- * next registration until application unregister.
- *
- * @return SIP REGISTER request.
- */
-PJ_DECL(pjsip_tx_data*) pjsip_regc_register(pjsip_regc *regc, pj_bool_t autoreg);
-
-
-/**
- * Create REGISTER request to unregister all contacts from server records.
- *
- * @param regc The client registration structure.
- *
- * @return SIP REGISTER request.
- */
-PJ_DECL(pjsip_tx_data*) pjsip_regc_unregister(pjsip_regc *regc);
-
-/**
- * Update Contact details in the client registration structure.
- *
- * @param regc The client registration structure.
- * @param ccnt Number of contacts.
- * @param contact Array of contacts.
- * @return zero if sucessfull.
- */
-PJ_DECL(pj_status_t) pjsip_regc_update_contact( pjsip_regc *regc,
- int ccnt,
- const pj_str_t contact[] );
-
-/**
- * Update the expires value.
- *
- * @param regc The client registration structure.
- * @param expires The new expires value.
- * @return zero on successfull.
- */
-PJ_DECL(pj_status_t) pjsip_regc_update_expires( pjsip_regc *regc,
- pj_uint32_t expires );
-
-/**
- * Sends outgoing REGISTER request.
- * The process will complete asynchronously, and application
- * will be notified via the callback when the process completes.
- *
- * @param regc The client registration structure.
- * @param tdata Transmit data.
- */
-PJ_DECL(void) pjsip_regc_send(pjsip_regc *regc, pjsip_tx_data *tdata);
-
-
-PJ_END_DECL
-
-#endif /* __PJSIP_REG_H__ */
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIP_REG_H__ +#define __PJSIP_SIP_REG_H__ + +/** + * @file sip_reg.h + * @brief SIP Registration Client + */ + +#include <pjsip/sip_types.h> +#include <pjsip/sip_auth.h> +#include <pjsip_mod_ua/sip_ua.h> + +PJ_BEGIN_DECL + +/** + * @defgroup PJSUA_REGC SIP Registration Client + * @ingroup PJSUA + * @{ + * \brief + * API for performing registration for user agent. + */ + +/** Typedef for client registration data. */ +typedef struct pjsip_regc pjsip_regc; + +/** Maximum contacts in registration. */ +#define PJSIP_REGC_MAX_CONTACT 10 + +/** Expiration not specified. */ +#define PJSIP_REGC_EXPIRATION_NOT_SPECIFIED ((pj_uint32_t)0xFFFFFFFFUL) + +/** Buffer to hold all contacts. */ +#define PJSIP_REGC_CONTACT_BUF_SIZE 512 + +/** Structure to hold parameters when calling application's callback. + * The application's callback is called when the client registration process + * has finished. + */ +struct pjsip_regc_cbparam +{ + pjsip_regc *regc; + void *token; + int code; + pj_str_t reason; + pjsip_rx_data *rdata; + int contact_cnt; + int expiration; + pjsip_contact_hdr *contact[PJSIP_REGC_MAX_CONTACT]; +}; + + +/** Type declaration for callback to receive registration result. */ +typedef void pjsip_regc_cb(struct pjsip_regc_cbparam *param); + + +/** + * Get the module instance for client registration module. + * + * @return client registration module. + */ +PJ_DECL(pjsip_module*) pjsip_regc_get_module(void); + + +/** + * Create client registration structure. + * + * @param endpt Endpoint, used to allocate pool from. + * @param token A data to be associated with the client registration struct. + * @param cb Pointer to callback function to receive registration status. + * + * @return client registration structure. + */ +PJ_DECL(pjsip_regc*) pjsip_regc_create( pjsip_endpoint *endpt, void *token, + pjsip_regc_cb *cb); + + +/** + * Destroy client registration structure. If a registration transaction is + * in progress, then the structure will be deleted only after a final response + * has been received, and in this case, the callback won't be called. + * + * @param regc The client registration structure. + */ +PJ_DECL(void) pjsip_regc_destroy(pjsip_regc *regc); + +/** + * Get the memory pool associated with a registration client handle. + * + * @param regc The client registration structure. + * @return pool handle. + */ +PJ_DECL(pj_pool_t*) pjsip_regc_get_pool(pjsip_regc *regc); + +/** + * Initialize client registration structure with various information needed to + * perform the registration. + * + * @param regc The client registration structure. + * @param from_url The person performing the registration, must be a SIP URL type. + * @param to_url The address of record for which the registration is targetd, must + * be a SIP/SIPS URL. + * @param ccnt Number of contacts in the array. + * @param contact Array of contacts. + * @param expires Default expiration interval (in seconds) to be applied for + * contact URL that doesn't have expiration settings. If the + * value PJSIP_REGC_EXPIRATION_NOT_SPECIFIED is given, then + * no default expiration will be applied. + * @return zero on success. + */ +PJ_DECL(pj_status_t) pjsip_regc_init(pjsip_regc *regc, + const pj_str_t *srv_url, + const pj_str_t *from_url, + const pj_str_t *to_url, + int ccnt, + const pj_str_t contact[], + pj_uint32_t expires); + + +/** + * Set authentication credentials to use by this registration. + * + * @param dlg The registration structure. + * @param count Number of credentials in the array. + * @param cred Array of credentials. + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_regc_set_credentials( pjsip_regc *regc, + int count, + const pjsip_cred_info cred[] ); + +/** + * Create REGISTER request for the specified client registration structure. + * + * After successfull registration, application can inspect the contacts in + * the client registration structure to list what contacts are associaciated + * with the address of record being targeted in the registration. + * + * @param regc The client registration structure. + * @param autoreg If non zero, the library will automatically refresh the + * next registration until application unregister. + * + * @return SIP REGISTER request. + */ +PJ_DECL(pjsip_tx_data*) pjsip_regc_register(pjsip_regc *regc, pj_bool_t autoreg); + + +/** + * Create REGISTER request to unregister all contacts from server records. + * + * @param regc The client registration structure. + * + * @return SIP REGISTER request. + */ +PJ_DECL(pjsip_tx_data*) pjsip_regc_unregister(pjsip_regc *regc); + +/** + * Update Contact details in the client registration structure. + * + * @param regc The client registration structure. + * @param ccnt Number of contacts. + * @param contact Array of contacts. + * @return zero if sucessfull. + */ +PJ_DECL(pj_status_t) pjsip_regc_update_contact( pjsip_regc *regc, + int ccnt, + const pj_str_t contact[] ); + +/** + * Update the expires value. + * + * @param regc The client registration structure. + * @param expires The new expires value. + * @return zero on successfull. + */ +PJ_DECL(pj_status_t) pjsip_regc_update_expires( pjsip_regc *regc, + pj_uint32_t expires ); + +/** + * Sends outgoing REGISTER request. + * The process will complete asynchronously, and application + * will be notified via the callback when the process completes. + * + * @param regc The client registration structure. + * @param tdata Transmit data. + */ +PJ_DECL(void) pjsip_regc_send(pjsip_regc *regc, pjsip_tx_data *tdata); + + +PJ_END_DECL + +#endif /* __PJSIP_REG_H__ */ diff --git a/pjsip/include/pjsip-ua/sip_ua.h b/pjsip/include/pjsip-ua/sip_ua.h index d2cc605a..92bf0db1 100644 --- a/pjsip/include/pjsip-ua/sip_ua.h +++ b/pjsip/include/pjsip-ua/sip_ua.h @@ -1,97 +1,97 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIP_UA_H__
-#define __PJSIP_SIP_UA_H__
-
-/**
- * @file ua.h
- * @brief SIP User Agent Library
- */
-
-#include <pjsip_mod_ua/sip_dialog.h>
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJSUA SIP User Agent Stack
- */
-
-/**
- * @defgroup PJSUA_UA SIP User Agent
- * @ingroup PJSUA
- * @{
- * \brief
- * User Agent manages the interactions between application and SIP dialogs.
- */
-
-typedef struct pjsip_dlg_callback pjsip_dlg_callback;
-
-/**
- * \brief This structure describes a User Agent instance.
- */
-struct pjsip_user_agent
-{
- pjsip_endpoint *endpt;
- pj_pool_t *pool;
- pj_mutex_t *mutex;
- pj_uint32_t mod_id;
- pj_hash_table_t *dlg_table;
- pjsip_dlg_callback *dlg_cb;
- pj_list dlg_list;
-};
-
-/**
- * Create a new dialog.
- */
-PJ_DECL(pjsip_dlg*) pjsip_ua_create_dialog( pjsip_user_agent *ua,
- pjsip_role_e role );
-
-
-/**
- * Destroy dialog.
- */
-PJ_DECL(void) pjsip_ua_destroy_dialog( pjsip_dlg *dlg );
-
-
-/**
- * Register callback to receive dialog notifications.
- */
-PJ_DECL(void) pjsip_ua_set_dialog_callback( pjsip_user_agent *ua,
- pjsip_dlg_callback *cb );
-
-
-/**
- * Get the module interface for the UA module.
- */
-PJ_DECL(pjsip_module*) pjsip_ua_get_module(void);
-
-
-/**
- * Dump user agent state to log file.
- */
-PJ_DECL(void) pjsip_ua_dump( pjsip_user_agent *ua );
-
-/**
- * @}
- */
-
-PJ_END_DECL
-
-#endif /* __PJSIP_UA_H__ */
-
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIP_UA_H__ +#define __PJSIP_SIP_UA_H__ + +/** + * @file ua.h + * @brief SIP User Agent Library + */ + +#include <pjsip_mod_ua/sip_dialog.h> + +PJ_BEGIN_DECL + +/** + * @defgroup PJSUA SIP User Agent Stack + */ + +/** + * @defgroup PJSUA_UA SIP User Agent + * @ingroup PJSUA + * @{ + * \brief + * User Agent manages the interactions between application and SIP dialogs. + */ + +typedef struct pjsip_dlg_callback pjsip_dlg_callback; + +/** + * \brief This structure describes a User Agent instance. + */ +struct pjsip_user_agent +{ + pjsip_endpoint *endpt; + pj_pool_t *pool; + pj_mutex_t *mutex; + pj_uint32_t mod_id; + pj_hash_table_t *dlg_table; + pjsip_dlg_callback *dlg_cb; + pj_list dlg_list; +}; + +/** + * Create a new dialog. + */ +PJ_DECL(pjsip_dlg*) pjsip_ua_create_dialog( pjsip_user_agent *ua, + pjsip_role_e role ); + + +/** + * Destroy dialog. + */ +PJ_DECL(void) pjsip_ua_destroy_dialog( pjsip_dlg *dlg ); + + +/** + * Register callback to receive dialog notifications. + */ +PJ_DECL(void) pjsip_ua_set_dialog_callback( pjsip_user_agent *ua, + pjsip_dlg_callback *cb ); + + +/** + * Get the module interface for the UA module. + */ +PJ_DECL(pjsip_module*) pjsip_ua_get_module(void); + + +/** + * Dump user agent state to log file. + */ +PJ_DECL(void) pjsip_ua_dump( pjsip_user_agent *ua ); + +/** + * @} + */ + +PJ_END_DECL + +#endif /* __PJSIP_UA_H__ */ + diff --git a/pjsip/include/pjsip/print_util.h b/pjsip/include/pjsip/print_util.h index 56f05851..b1362a72 100644 --- a/pjsip/include/pjsip/print_util.h +++ b/pjsip/include/pjsip/print_util.h @@ -1,144 +1,144 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_PRINT_H__
-#define __PJSIP_PRINT_H__
-
-/* Minimum space left in the buffer */
-#define MIN_SPACE 10
-
-#define copy_advance_check(buf,str) \
- do { \
- if ((str).slen+MIN_SPACE >= (endbuf-buf)) return -1; \
- pj_memcpy(buf, (str).ptr, (str).slen); \
- buf += (str).slen; \
- } while (0)
-
-/*
-static char *imp_copy_advance_pair(char *buf, char *endbuf, const char *str1, int len1, const pj_str_t *str2)
-{
- if (str2->slen) {
- int printed = len1+str2->slen;
- if (printed+MIN_SPACE >= (endbuf-buf)) return NULL;
- pj_memcpy(buf,str1,len1);
- pj_memcpy(buf+len1, str2->ptr, str2->slen);
- return buf + printed;
- } else
- return buf;
-}
-*/
-
-#define copy_advance_pair_check(buf,str1,len1,str2) \
- do { \
- if (str2.slen) { \
- printed = len1+str2.slen; \
- if (printed+MIN_SPACE >= (endbuf-buf)) return -1; \
- pj_memcpy(buf,str1,len1); \
- pj_memcpy(buf+len1, str2.ptr, str2.slen); \
- buf += printed; \
- } \
- } while (0)
-/*
-#define copy_advance_pair(buf,str1,len1,str2) \
- do { \
- buf = imp_copy_advance_pair(buf, endbuf, str1, len1, &str2); \
- if (buf == NULL) return -1; \
- } while (0)
-*/
-
-#define copy_advance_pair_quote_check(buf,str1,len1,str2,quotebegin,quoteend) \
- do { \
- if (str2.slen) { \
- printed = len1+str2.slen+2; \
- if (printed+MIN_SPACE >= (endbuf-buf)) return -1; \
- pj_memcpy(buf,str1,len1); \
- *(buf+len1)=quotebegin; \
- pj_memcpy(buf+len1+1, str2.ptr, str2.slen); \
- *(buf+printed-1) = quoteend; \
- buf += printed; \
- } \
- } while (0)
-
-#define copy_advance_pair_escape(buf,str1,len1,str2,unres) \
- do { \
- if (str2.slen) { \
- pj_ssize_t esc_len; \
- if (len1+str2.slen+MIN_SPACE >= (endbuf-buf)) return -1; \
- pj_memcpy(buf,str1,len1); \
- buf += len1; \
- esc_len=pj_strncpy2_escape(buf, &str2, (endbuf-buf), &unres); \
- if (esc_len < 0) return -1; \
- buf += esc_len; \
- if (endbuf-buf < MIN_SPACE) return -1; \
- } \
- } while (0)
-
-
-#define copy_advance_no_check(buf,str) \
- do { \
- pj_memcpy(buf, (str).ptr, (str).slen); \
- buf += (str).slen; \
- } while (0)
-
-#define copy_advance_escape(buf,str,unres) \
- do { \
- pj_ssize_t len = \
- pj_strncpy2_escape(buf, &(str), (endbuf-buf), &(unres)); \
- if (len < 0) return -1; \
- buf += len; \
- if (endbuf-buf < MIN_SPACE) return -1; \
- } while (0)
-
-#define copy_advance_pair_no_check(buf,str1,len1,str2) \
- if (str2.slen) { \
- pj_memcpy(buf,str1,len1); \
- pj_memcpy(buf+len1, str2.ptr, str2.slen); \
- buf += len1+str2.slen; \
- }
-
-#define copy_advance copy_advance_check
-#define copy_advance_pair copy_advance_pair_check
-#define copy_advance_pair_quote copy_advance_pair_quote_check
-
-#define copy_advance_pair_quote_cond(buf,str1,len1,str2,quotebegin,quoteend) \
- do { \
- if (str2.slen && *str2.ptr!=quotebegin) \
- copy_advance_pair_quote(buf,str1,len1,str2,quotebegin,quoteend); \
- else \
- copy_advance_pair(buf,str1,len1,str2); \
- } while (0)
-
-/*
- * Internal type declarations.
- */
-typedef void* (*pjsip_hdr_clone_fptr)(pj_pool_t *, const void*);
-typedef int (*pjsip_hdr_print_fptr)(void *hdr, char *buf, pj_size_t len);
-
-extern const pj_str_t pjsip_hdr_names[];
-
-PJ_INLINE(void) init_hdr(void *hptr, pjsip_hdr_e htype, void *vptr)
-{
- pjsip_hdr *hdr = hptr;
- hdr->type = htype;
- hdr->name = hdr->sname = pjsip_hdr_names[htype];
- hdr->vptr = vptr;
- pj_list_init(hdr);
-}
-
-#endif /* __PJSIP_PRINT_H__ */
-
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_PRINT_H__ +#define __PJSIP_PRINT_H__ + +/* Minimum space left in the buffer */ +#define MIN_SPACE 10 + +#define copy_advance_check(buf,str) \ + do { \ + if ((str).slen+MIN_SPACE >= (endbuf-buf)) return -1; \ + pj_memcpy(buf, (str).ptr, (str).slen); \ + buf += (str).slen; \ + } while (0) + +/* +static char *imp_copy_advance_pair(char *buf, char *endbuf, const char *str1, int len1, const pj_str_t *str2) +{ + if (str2->slen) { + int printed = len1+str2->slen; + if (printed+MIN_SPACE >= (endbuf-buf)) return NULL; + pj_memcpy(buf,str1,len1); + pj_memcpy(buf+len1, str2->ptr, str2->slen); + return buf + printed; + } else + return buf; +} +*/ + +#define copy_advance_pair_check(buf,str1,len1,str2) \ + do { \ + if (str2.slen) { \ + printed = len1+str2.slen; \ + if (printed+MIN_SPACE >= (endbuf-buf)) return -1; \ + pj_memcpy(buf,str1,len1); \ + pj_memcpy(buf+len1, str2.ptr, str2.slen); \ + buf += printed; \ + } \ + } while (0) +/* +#define copy_advance_pair(buf,str1,len1,str2) \ + do { \ + buf = imp_copy_advance_pair(buf, endbuf, str1, len1, &str2); \ + if (buf == NULL) return -1; \ + } while (0) +*/ + +#define copy_advance_pair_quote_check(buf,str1,len1,str2,quotebegin,quoteend) \ + do { \ + if (str2.slen) { \ + printed = len1+str2.slen+2; \ + if (printed+MIN_SPACE >= (endbuf-buf)) return -1; \ + pj_memcpy(buf,str1,len1); \ + *(buf+len1)=quotebegin; \ + pj_memcpy(buf+len1+1, str2.ptr, str2.slen); \ + *(buf+printed-1) = quoteend; \ + buf += printed; \ + } \ + } while (0) + +#define copy_advance_pair_escape(buf,str1,len1,str2,unres) \ + do { \ + if (str2.slen) { \ + pj_ssize_t esc_len; \ + if (len1+str2.slen+MIN_SPACE >= (endbuf-buf)) return -1; \ + pj_memcpy(buf,str1,len1); \ + buf += len1; \ + esc_len=pj_strncpy2_escape(buf, &str2, (endbuf-buf), &unres); \ + if (esc_len < 0) return -1; \ + buf += esc_len; \ + if (endbuf-buf < MIN_SPACE) return -1; \ + } \ + } while (0) + + +#define copy_advance_no_check(buf,str) \ + do { \ + pj_memcpy(buf, (str).ptr, (str).slen); \ + buf += (str).slen; \ + } while (0) + +#define copy_advance_escape(buf,str,unres) \ + do { \ + pj_ssize_t len = \ + pj_strncpy2_escape(buf, &(str), (endbuf-buf), &(unres)); \ + if (len < 0) return -1; \ + buf += len; \ + if (endbuf-buf < MIN_SPACE) return -1; \ + } while (0) + +#define copy_advance_pair_no_check(buf,str1,len1,str2) \ + if (str2.slen) { \ + pj_memcpy(buf,str1,len1); \ + pj_memcpy(buf+len1, str2.ptr, str2.slen); \ + buf += len1+str2.slen; \ + } + +#define copy_advance copy_advance_check +#define copy_advance_pair copy_advance_pair_check +#define copy_advance_pair_quote copy_advance_pair_quote_check + +#define copy_advance_pair_quote_cond(buf,str1,len1,str2,quotebegin,quoteend) \ + do { \ + if (str2.slen && *str2.ptr!=quotebegin) \ + copy_advance_pair_quote(buf,str1,len1,str2,quotebegin,quoteend); \ + else \ + copy_advance_pair(buf,str1,len1,str2); \ + } while (0) + +/* + * Internal type declarations. + */ +typedef void* (*pjsip_hdr_clone_fptr)(pj_pool_t *, const void*); +typedef int (*pjsip_hdr_print_fptr)(void *hdr, char *buf, pj_size_t len); + +extern const pj_str_t pjsip_hdr_names[]; + +PJ_INLINE(void) init_hdr(void *hptr, pjsip_hdr_e htype, void *vptr) +{ + pjsip_hdr *hdr = hptr; + hdr->type = htype; + hdr->name = hdr->sname = pjsip_hdr_names[htype]; + hdr->vptr = vptr; + pj_list_init(hdr); +} + +#endif /* __PJSIP_PRINT_H__ */ + diff --git a/pjsip/include/pjsip/sip_auth.h b/pjsip/include/pjsip/sip_auth.h index 56a5fe26..7d8b9c62 100644 --- a/pjsip/include/pjsip/sip_auth.h +++ b/pjsip/include/pjsip/sip_auth.h @@ -1,247 +1,247 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_AUTH_SIP_AUTH_H__
-#define __PJSIP_AUTH_SIP_AUTH_H__
-
-/**
- * @file pjsip_auth.h
- * @brief SIP Authorization Module.
- */
-
-#include <pjsip/sip_config.h>
-#include <pjsip/sip_auth_msg.h>
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJSIP_AUTH_API Authorization API's
- * @ingroup PJSIP_AUTH
- * @{
- */
-
- /** Type of data in the credential information. */
-typedef enum pjsip_cred_data_type
-{
- PJSIP_CRED_DATA_PLAIN_PASSWD, /**< Plain text password. */
- PJSIP_CRED_DATA_DIGEST, /**< Hashed digest. */
-} pjsip_cred_data_type;
-
-/** Authentication's quality of protection (qop) type. */
-typedef enum pjsip_auth_qop_type
-{
- PJSIP_AUTH_QOP_NONE, /**< No quality of protection. */
- PJSIP_AUTH_QOP_AUTH, /**< Authentication. */
- PJSIP_AUTH_QOP_AUTH_INT, /**< Authentication with integrity protection. */
- PJSIP_AUTH_QOP_UNKNOWN, /**< Unknown protection. */
-} pjsip_auth_qop_type;
-
-
-/**
- * This structure describes credential information.
- * A credential information is a static, persistent information that identifies
- * username and password required to authorize to a specific realm.
- */
-struct pjsip_cred_info
-{
- pj_str_t realm; /**< Realm. */
- pj_str_t scheme; /**< Scheme. */
- pj_str_t username; /**< User name. */
- int data_type; /**< Type of data. */
- pj_str_t data; /**< The data, which can be a plaintext
- password or a hashed digest. */
-};
-
-/**
- * This structure describes cached value of previously sent Authorization
- * or Proxy-Authorization header. The authentication framework keeps a list
- * of this structure and will resend the same header to the same server
- * as long as the method, uri, and nonce stays the same.
- */
-typedef struct pjsip_cached_auth_hdr
-{
- PJ_DECL_LIST_MEMBER(struct pjsip_cached_auth_hdr);
-
- pjsip_method method;
- pjsip_authorization_hdr *hdr;
-
-} pjsip_cached_auth_hdr;
-
-
-/**
- * This structure describes authentication information for the specified
- * realm. Each instance of this structure describes authentication "session"
- * between this endpoint and remote server. This "session" information is
- * usefull to keep information that persists for more than one challenge,
- * such as nonce-count and cnonce value.
- *
- * Other than that, this structure also keeps the last authorization headers
- * that have been sent in the cache list.
- */
-typedef struct pjsip_auth_session
-{
- PJ_DECL_LIST_MEMBER(struct pjsip_auth_session);
-
- pj_str_t realm;
- pj_bool_t is_proxy;
- pjsip_auth_qop_type qop_value;
-#if PJSIP_AUTH_QOP_SUPPORT
- pj_uint32_t nc;
- pj_str_t cnonce;
-#endif
-#if PJSIP_AUTH_AUTO_SEND_NEXT
- pjsip_www_authenticate_hdr *last_chal;
-#endif
-#if PJSIP_AUTH_HEADER_CACHING
- pjsip_cached_auth_hdr cached_hdr;
-#endif
-
-} pjsip_auth_session;
-
-
-/**
- * Create authorization header for the specified credential.
- * Application calls this function to create Authorization or Proxy-Authorization
- * header after receiving WWW-Authenticate or Proxy-Authenticate challenge
- * (normally in 401/407 response).
- * If authorization session argument is specified, this function will update
- * the session with the updated information if required (e.g. to update
- * nonce-count when qop is "auth" or "auth-int"). This function will also
- * save the authorization header in the session's cached header list.
- *
- * @param req_pool Pool to allocate new header for the request.
- * @param hdr The WWW-Authenticate or Proxy-Authenticate found in
- * the response.
- * @param uri The URI for which authorization is targeted to.
- * @param cred_info The credential to be used for authentication.
- * @param method The method.
- * @param sess_pool Session pool to update session or to allocate message
- * in the cache. May be NULL if auth_sess is NULL.
- * @param auth_sess If not NULL, this specifies the specific authentication
- * session to be used or updated.
- *
- * @return The Authorization header, which can be typecasted to
- * Proxy-Authorization.
- */
-PJ_DECL(pjsip_authorization_hdr*) pjsip_auth_respond(
- pj_pool_t *req_pool,
- const pjsip_www_authenticate_hdr *hdr,
- const pjsip_uri *uri,
- const pjsip_cred_info *cred_info,
- const pjsip_method *method,
- pj_pool_t *sess_pool,
- pjsip_auth_session *auth_sess);
-
-/**
- * Verify digest in the authorization request.
- *
- * @param hdr The incoming Authorization/Proxy-Authorization header.
- * @param method The method.
- * @param password The plaintext password to verify.
- *
- * @return Non-zero if authorization succeed.
- */
-PJ_DECL(pj_bool_t) pjsip_auth_verify( const pjsip_authorization_hdr *hdr,
- const pj_str_t *method,
- const pjsip_cred_info *cred_info );
-
-
-/**
- * This function can be used to find credential information which matches
- * the specified realm.
- *
- * @param count Number of credentials in the parameter.
- * @param cred The array of credentials.
- * @param realm Realm to search.
- * @param scheme Authentication scheme.
- *
- * @return The credential which matches the specified realm.
- */
-PJ_DECL(const pjsip_cred_info*) pjsip_auth_find_cred( unsigned count,
- const pjsip_cred_info cred[],
- const pj_str_t *realm,
- const pj_str_t *scheme );
-
-
-/**
- * Initialize new request message with authorization headers.
- * This function will put Authorization/Proxy-Authorization headers to the
- * outgoing request message. If caching is enabled (PJSIP_AUTH_HEADER_CACHING)
- * and the session has previously sent Authorization/Proxy-Authorization header
- * with the same method, then the same Authorization/Proxy-Authorization header
- * will be resent from the cache only if qop is not present. If the stack is
- * configured to automatically generate next Authorization/Proxy-Authorization
- * headers (PJSIP_AUTH_AUTO_SEND_NEXT flag), then new Authorization/Proxy-
- * Authorization headers are calculated and generated when they are not present
- * in the case or if authorization session has qop.
- *
- * If both PJSIP_AUTH_HEADER_CACHING flag and PJSIP_AUTH_AUTO_SEND_NEXT flag
- * are not set, this function will do nothing. The stack then will only send
- * Authorization/Proxy-Authorization to respond 401/407 response.
- *
- * @param sess_pool Session level pool, where memory will be allocated from
- * for data that persists across requests (e.g. caching).
- * @param tdata The request message to be initialized.
- * @param sess_list List of authorization sessions that have been recorded.
- * @param cred_count Number of credentials.
- * @param cred_info Array of credentials.
- *
- * @return Zero if successfull.
- */
-PJ_DECL(pj_status_t) pjsip_auth_init_req( pj_pool_t *sess_pool,
- pjsip_tx_data *tdata,
- pjsip_auth_session *sess_list,
- int cred_count,
- const pjsip_cred_info cred_info[]);
-
-/**
- * Call this function when a transaction failed with 401 or 407 response.
- * This function will reinitialize the original request message with the
- * authentication challenge found in the response message, and add the
- * new authorization header in the authorization cache.
- *
- * Note that upon return the reference counter of the transmit data
- * will be incremented.
- *
- * @param endpt Endpoint.
- * @param pool The pool to allocate memory for new cred_info.
- * @param cached_list Cached authorization headers.
- * @param cred_count Number of credentials.
- * @param cred_info Array of credentials to use.
- * @param tdata The original request message, which normally can be
- * retrieved from tsx->last_tx.
- * @param rdata The response message containing 401/407 status.
- *
- * @return New transmit data buffer, or NULL if the dialog
- * can not respond to the authorization challenge.
- */
-PJ_DECL(pjsip_tx_data*)
-pjsip_auth_reinit_req( pjsip_endpoint *endpt,
- pj_pool_t *ses_pool,
- pjsip_auth_session *sess_list,
- int cred_count, const pjsip_cred_info cred_info[],
- pjsip_tx_data *tdata, const pjsip_rx_data *rdata);
-
-/**
- * @}
- */
-
-PJ_END_DECL
-
-#endif /* __PJSIP_AUTH_SIP_AUTH_H__ */
-
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_AUTH_SIP_AUTH_H__ +#define __PJSIP_AUTH_SIP_AUTH_H__ + +/** + * @file pjsip_auth.h + * @brief SIP Authorization Module. + */ + +#include <pjsip/sip_config.h> +#include <pjsip/sip_auth_msg.h> + +PJ_BEGIN_DECL + +/** + * @defgroup PJSIP_AUTH_API Authorization API's + * @ingroup PJSIP_AUTH + * @{ + */ + + /** Type of data in the credential information. */ +typedef enum pjsip_cred_data_type +{ + PJSIP_CRED_DATA_PLAIN_PASSWD, /**< Plain text password. */ + PJSIP_CRED_DATA_DIGEST, /**< Hashed digest. */ +} pjsip_cred_data_type; + +/** Authentication's quality of protection (qop) type. */ +typedef enum pjsip_auth_qop_type +{ + PJSIP_AUTH_QOP_NONE, /**< No quality of protection. */ + PJSIP_AUTH_QOP_AUTH, /**< Authentication. */ + PJSIP_AUTH_QOP_AUTH_INT, /**< Authentication with integrity protection. */ + PJSIP_AUTH_QOP_UNKNOWN, /**< Unknown protection. */ +} pjsip_auth_qop_type; + + +/** + * This structure describes credential information. + * A credential information is a static, persistent information that identifies + * username and password required to authorize to a specific realm. + */ +struct pjsip_cred_info +{ + pj_str_t realm; /**< Realm. */ + pj_str_t scheme; /**< Scheme. */ + pj_str_t username; /**< User name. */ + int data_type; /**< Type of data. */ + pj_str_t data; /**< The data, which can be a plaintext + password or a hashed digest. */ +}; + +/** + * This structure describes cached value of previously sent Authorization + * or Proxy-Authorization header. The authentication framework keeps a list + * of this structure and will resend the same header to the same server + * as long as the method, uri, and nonce stays the same. + */ +typedef struct pjsip_cached_auth_hdr +{ + PJ_DECL_LIST_MEMBER(struct pjsip_cached_auth_hdr); + + pjsip_method method; + pjsip_authorization_hdr *hdr; + +} pjsip_cached_auth_hdr; + + +/** + * This structure describes authentication information for the specified + * realm. Each instance of this structure describes authentication "session" + * between this endpoint and remote server. This "session" information is + * usefull to keep information that persists for more than one challenge, + * such as nonce-count and cnonce value. + * + * Other than that, this structure also keeps the last authorization headers + * that have been sent in the cache list. + */ +typedef struct pjsip_auth_session +{ + PJ_DECL_LIST_MEMBER(struct pjsip_auth_session); + + pj_str_t realm; + pj_bool_t is_proxy; + pjsip_auth_qop_type qop_value; +#if PJSIP_AUTH_QOP_SUPPORT + pj_uint32_t nc; + pj_str_t cnonce; +#endif +#if PJSIP_AUTH_AUTO_SEND_NEXT + pjsip_www_authenticate_hdr *last_chal; +#endif +#if PJSIP_AUTH_HEADER_CACHING + pjsip_cached_auth_hdr cached_hdr; +#endif + +} pjsip_auth_session; + + +/** + * Create authorization header for the specified credential. + * Application calls this function to create Authorization or Proxy-Authorization + * header after receiving WWW-Authenticate or Proxy-Authenticate challenge + * (normally in 401/407 response). + * If authorization session argument is specified, this function will update + * the session with the updated information if required (e.g. to update + * nonce-count when qop is "auth" or "auth-int"). This function will also + * save the authorization header in the session's cached header list. + * + * @param req_pool Pool to allocate new header for the request. + * @param hdr The WWW-Authenticate or Proxy-Authenticate found in + * the response. + * @param uri The URI for which authorization is targeted to. + * @param cred_info The credential to be used for authentication. + * @param method The method. + * @param sess_pool Session pool to update session or to allocate message + * in the cache. May be NULL if auth_sess is NULL. + * @param auth_sess If not NULL, this specifies the specific authentication + * session to be used or updated. + * + * @return The Authorization header, which can be typecasted to + * Proxy-Authorization. + */ +PJ_DECL(pjsip_authorization_hdr*) pjsip_auth_respond( + pj_pool_t *req_pool, + const pjsip_www_authenticate_hdr *hdr, + const pjsip_uri *uri, + const pjsip_cred_info *cred_info, + const pjsip_method *method, + pj_pool_t *sess_pool, + pjsip_auth_session *auth_sess); + +/** + * Verify digest in the authorization request. + * + * @param hdr The incoming Authorization/Proxy-Authorization header. + * @param method The method. + * @param password The plaintext password to verify. + * + * @return Non-zero if authorization succeed. + */ +PJ_DECL(pj_bool_t) pjsip_auth_verify( const pjsip_authorization_hdr *hdr, + const pj_str_t *method, + const pjsip_cred_info *cred_info ); + + +/** + * This function can be used to find credential information which matches + * the specified realm. + * + * @param count Number of credentials in the parameter. + * @param cred The array of credentials. + * @param realm Realm to search. + * @param scheme Authentication scheme. + * + * @return The credential which matches the specified realm. + */ +PJ_DECL(const pjsip_cred_info*) pjsip_auth_find_cred( unsigned count, + const pjsip_cred_info cred[], + const pj_str_t *realm, + const pj_str_t *scheme ); + + +/** + * Initialize new request message with authorization headers. + * This function will put Authorization/Proxy-Authorization headers to the + * outgoing request message. If caching is enabled (PJSIP_AUTH_HEADER_CACHING) + * and the session has previously sent Authorization/Proxy-Authorization header + * with the same method, then the same Authorization/Proxy-Authorization header + * will be resent from the cache only if qop is not present. If the stack is + * configured to automatically generate next Authorization/Proxy-Authorization + * headers (PJSIP_AUTH_AUTO_SEND_NEXT flag), then new Authorization/Proxy- + * Authorization headers are calculated and generated when they are not present + * in the case or if authorization session has qop. + * + * If both PJSIP_AUTH_HEADER_CACHING flag and PJSIP_AUTH_AUTO_SEND_NEXT flag + * are not set, this function will do nothing. The stack then will only send + * Authorization/Proxy-Authorization to respond 401/407 response. + * + * @param sess_pool Session level pool, where memory will be allocated from + * for data that persists across requests (e.g. caching). + * @param tdata The request message to be initialized. + * @param sess_list List of authorization sessions that have been recorded. + * @param cred_count Number of credentials. + * @param cred_info Array of credentials. + * + * @return Zero if successfull. + */ +PJ_DECL(pj_status_t) pjsip_auth_init_req( pj_pool_t *sess_pool, + pjsip_tx_data *tdata, + pjsip_auth_session *sess_list, + int cred_count, + const pjsip_cred_info cred_info[]); + +/** + * Call this function when a transaction failed with 401 or 407 response. + * This function will reinitialize the original request message with the + * authentication challenge found in the response message, and add the + * new authorization header in the authorization cache. + * + * Note that upon return the reference counter of the transmit data + * will be incremented. + * + * @param endpt Endpoint. + * @param pool The pool to allocate memory for new cred_info. + * @param cached_list Cached authorization headers. + * @param cred_count Number of credentials. + * @param cred_info Array of credentials to use. + * @param tdata The original request message, which normally can be + * retrieved from tsx->last_tx. + * @param rdata The response message containing 401/407 status. + * + * @return New transmit data buffer, or NULL if the dialog + * can not respond to the authorization challenge. + */ +PJ_DECL(pjsip_tx_data*) +pjsip_auth_reinit_req( pjsip_endpoint *endpt, + pj_pool_t *ses_pool, + pjsip_auth_session *sess_list, + int cred_count, const pjsip_cred_info cred_info[], + pjsip_tx_data *tdata, const pjsip_rx_data *rdata); + +/** + * @} + */ + +PJ_END_DECL + +#endif /* __PJSIP_AUTH_SIP_AUTH_H__ */ + diff --git a/pjsip/include/pjsip/sip_auth_msg.h b/pjsip/include/pjsip/sip_auth_msg.h index 5ef74d23..81d6cd09 100644 --- a/pjsip/include/pjsip/sip_auth_msg.h +++ b/pjsip/include/pjsip/sip_auth_msg.h @@ -1,209 +1,213 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_AUTH_SIP_AUTH_MSG_H__
-#define __PJSIP_AUTH_SIP_AUTH_MSG_H__
-
-#include <pjsip/sip_msg.h>
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJSIP_MSG_AUTHORIZATION Header Field: Authorization and Proxy-Authorization
- * @brief Authorization and Proxy-Authorization header field.
- * @ingroup PJSIP_MSG
- * @{
- */
-
-/**
- * Common credential.
- */
-struct pjsip_common_credential
-{
- pj_str_t realm;
-};
-
-typedef struct pjsip_common_credential pjsip_common_credential;
-
-
-/**
- * This structure describe credential used in Authorization and
- * Proxy-Authorization header for digest authentication scheme.
- */
-struct pjsip_digest_credential
-{
- pj_str_t realm;
- pj_str_t username;
- pj_str_t nonce;
- pj_str_t uri;
- pj_str_t response;
- pj_str_t algorithm;
- pj_str_t cnonce;
- pj_str_t opaque;
- pj_str_t qop;
- pj_str_t nc;
- pj_str_t other_param;
-};
-
-typedef struct pjsip_digest_credential pjsip_digest_credential;
-
-/**
- * This structure describe credential used in Authorization and
- * Proxy-Authorization header for PGP authentication scheme.
- */
-struct pjsip_pgp_credential
-{
- pj_str_t realm;
- pj_str_t version;
- pj_str_t signature;
- pj_str_t signed_by;
- pj_str_t nonce;
-};
-
-typedef struct pjsip_pgp_credential pjsip_pgp_credential;
-
-/**
- * This structure describes SIP Authorization header (and also SIP
- * Proxy-Authorization header).
- */
-struct pjsip_authorization_hdr
-{
- PJSIP_DECL_HDR_MEMBER(struct pjsip_authorization_hdr);
- pj_str_t scheme;
- union
- {
- pjsip_common_credential common;
- pjsip_digest_credential digest;
- pjsip_pgp_credential pgp;
- } credential;
-};
-
-typedef struct pjsip_authorization_hdr pjsip_authorization_hdr;
-
-/** SIP Proxy-Authorization header shares the same structure as SIP
- Authorization header.
- */
-typedef struct pjsip_authorization_hdr pjsip_proxy_authorization_hdr;
-
-/**
- * Create SIP Authorization header.
- * @param pool Pool where memory will be allocated from.
- * @return SIP Authorization header.
- */
-PJ_DECL(pjsip_authorization_hdr*) pjsip_authorization_hdr_create(pj_pool_t *pool);
-
-/**
- * Create SIP Proxy-Authorization header.
- * @param pool Pool where memory will be allocated from.
- * @return SIP Proxy-Authorization header.
- */
-PJ_DECL(pjsip_proxy_authorization_hdr*) pjsip_proxy_authorization_hdr_create(pj_pool_t *pool);
-
-
-/**
- * @}
- */
-
-/**
- * @defgroup PJSIP_WWW_AUTH Header Field: Proxy-Authenticate and WWW-Authenticate
- * @brief Proxy-Authenticate and WWW-Authenticate.
- * @ingroup PJSIP_MSG
- * @{
- */
-
-struct pjsip_common_challenge
-{
- pj_str_t realm;
-};
-
-typedef struct pjsip_common_challenge pjsip_common_challenge;
-
-/**
- * This structure describes authentication challenge used in Proxy-Authenticate
- * or WWW-Authenticate for digest authentication scheme.
- */
-struct pjsip_digest_challenge
-{
- pj_str_t realm;
- pj_str_t domain;
- pj_str_t nonce;
- pj_str_t opaque;
- int stale;
- pj_str_t algorithm;
- pj_str_t qop;
- pj_str_t other_param;
-};
-
-typedef struct pjsip_digest_challenge pjsip_digest_challenge;
-
-/**
- * This structure describes authentication challenge used in Proxy-Authenticate
- * or WWW-Authenticate for PGP authentication scheme.
- */
-struct pjsip_pgp_challenge
-{
- pj_str_t realm;
- pj_str_t version;
- pj_str_t micalgorithm;
- pj_str_t pubalgorithm;
- pj_str_t nonce;
-};
-
-typedef struct pjsip_pgp_challenge pjsip_pgp_challenge;
-
-/**
- * This structure describe SIP WWW-Authenticate header (Proxy-Authenticate
- * header also uses the same structure).
- */
-struct pjsip_www_authenticate_hdr
-{
- PJSIP_DECL_HDR_MEMBER(struct pjsip_www_authenticate_hdr);
- pj_str_t scheme;
- union
- {
- pjsip_common_challenge common;
- pjsip_digest_challenge digest;
- pjsip_pgp_challenge pgp;
- } challenge;
-};
-
-typedef struct pjsip_www_authenticate_hdr pjsip_www_authenticate_hdr;
-typedef struct pjsip_www_authenticate_hdr pjsip_proxy_authenticate_hdr;
-
-
-/**
- * Create SIP WWW-Authenticate header.
- * @param pool Pool where memory will be allocated from.
- * @return SIP WWW-Authenticate header.
- */
-PJ_DECL(pjsip_www_authenticate_hdr*) pjsip_www_authenticate_hdr_create(pj_pool_t *pool);
-
-/**
- * Create SIP Proxy-Authenticate header.
- * @param pool Pool where memory will be allocated from.
- * @return SIP Proxy-Authenticate header.
- */
-PJ_DECL(pjsip_proxy_authenticate_hdr*) pjsip_proxy_authenticate_hdr_create(pj_pool_t *pool);
-
-/**
- * @}
- */
-
-PJ_END_DECL
-
-#endif /* __PJSIP_AUTH_SIP_AUTH_MSG_H__ */
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_AUTH_SIP_AUTH_MSG_H__ +#define __PJSIP_AUTH_SIP_AUTH_MSG_H__ + +#include <pjsip/sip_msg.h> + +PJ_BEGIN_DECL + +/** + * @defgroup PJSIP_MSG_AUTHORIZATION Header Field: Authorization and Proxy-Authorization + * @brief Authorization and Proxy-Authorization header field. + * @ingroup PJSIP_MSG + * @{ + */ + +/** + * Common credential. + */ +struct pjsip_common_credential +{ + pj_str_t realm; + pjsip_param other_param; +}; + +typedef struct pjsip_common_credential pjsip_common_credential; + + +/** + * This structure describe credential used in Authorization and + * Proxy-Authorization header for digest authentication scheme. + */ +struct pjsip_digest_credential +{ + pj_str_t realm; + pjsip_param other_param; + pj_str_t username; + pj_str_t nonce; + pj_str_t uri; + pj_str_t response; + pj_str_t algorithm; + pj_str_t cnonce; + pj_str_t opaque; + pj_str_t qop; + pj_str_t nc; +}; + +typedef struct pjsip_digest_credential pjsip_digest_credential; + +/** + * This structure describe credential used in Authorization and + * Proxy-Authorization header for PGP authentication scheme. + */ +struct pjsip_pgp_credential +{ + pj_str_t realm; + pjsip_param other_param; + pj_str_t version; + pj_str_t signature; + pj_str_t signed_by; + pj_str_t nonce; +}; + +typedef struct pjsip_pgp_credential pjsip_pgp_credential; + +/** + * This structure describes SIP Authorization header (and also SIP + * Proxy-Authorization header). + */ +struct pjsip_authorization_hdr +{ + PJSIP_DECL_HDR_MEMBER(struct pjsip_authorization_hdr); + pj_str_t scheme; + union + { + pjsip_common_credential common; + pjsip_digest_credential digest; + pjsip_pgp_credential pgp; + } credential; +}; + +typedef struct pjsip_authorization_hdr pjsip_authorization_hdr; + +/** SIP Proxy-Authorization header shares the same structure as SIP + Authorization header. + */ +typedef struct pjsip_authorization_hdr pjsip_proxy_authorization_hdr; + +/** + * Create SIP Authorization header. + * @param pool Pool where memory will be allocated from. + * @return SIP Authorization header. + */ +PJ_DECL(pjsip_authorization_hdr*) pjsip_authorization_hdr_create(pj_pool_t *pool); + +/** + * Create SIP Proxy-Authorization header. + * @param pool Pool where memory will be allocated from. + * @return SIP Proxy-Authorization header. + */ +PJ_DECL(pjsip_proxy_authorization_hdr*) pjsip_proxy_authorization_hdr_create(pj_pool_t *pool); + + +/** + * @} + */ + +/** + * @defgroup PJSIP_WWW_AUTH Header Field: Proxy-Authenticate and WWW-Authenticate + * @brief Proxy-Authenticate and WWW-Authenticate. + * @ingroup PJSIP_MSG + * @{ + */ + +struct pjsip_common_challenge +{ + pj_str_t realm; + pjsip_param other_param; +}; + +typedef struct pjsip_common_challenge pjsip_common_challenge; + +/** + * This structure describes authentication challenge used in Proxy-Authenticate + * or WWW-Authenticate for digest authentication scheme. + */ +struct pjsip_digest_challenge +{ + pj_str_t realm; + pjsip_param other_param; + pj_str_t domain; + pj_str_t nonce; + pj_str_t opaque; + int stale; + pj_str_t algorithm; + pj_str_t qop; +}; + +typedef struct pjsip_digest_challenge pjsip_digest_challenge; + +/** + * This structure describes authentication challenge used in Proxy-Authenticate + * or WWW-Authenticate for PGP authentication scheme. + */ +struct pjsip_pgp_challenge +{ + pj_str_t realm; + pjsip_param other_param; + pj_str_t version; + pj_str_t micalgorithm; + pj_str_t pubalgorithm; + pj_str_t nonce; +}; + +typedef struct pjsip_pgp_challenge pjsip_pgp_challenge; + +/** + * This structure describe SIP WWW-Authenticate header (Proxy-Authenticate + * header also uses the same structure). + */ +struct pjsip_www_authenticate_hdr +{ + PJSIP_DECL_HDR_MEMBER(struct pjsip_www_authenticate_hdr); + pj_str_t scheme; + union + { + pjsip_common_challenge common; + pjsip_digest_challenge digest; + pjsip_pgp_challenge pgp; + } challenge; +}; + +typedef struct pjsip_www_authenticate_hdr pjsip_www_authenticate_hdr; +typedef struct pjsip_www_authenticate_hdr pjsip_proxy_authenticate_hdr; + + +/** + * Create SIP WWW-Authenticate header. + * @param pool Pool where memory will be allocated from. + * @return SIP WWW-Authenticate header. + */ +PJ_DECL(pjsip_www_authenticate_hdr*) pjsip_www_authenticate_hdr_create(pj_pool_t *pool); + +/** + * Create SIP Proxy-Authenticate header. + * @param pool Pool where memory will be allocated from. + * @return SIP Proxy-Authenticate header. + */ +PJ_DECL(pjsip_proxy_authenticate_hdr*) pjsip_proxy_authenticate_hdr_create(pj_pool_t *pool); + +/** + * @} + */ + +PJ_END_DECL + +#endif /* __PJSIP_AUTH_SIP_AUTH_MSG_H__ */ diff --git a/pjsip/include/pjsip/sip_auth_parser.h b/pjsip/include/pjsip/sip_auth_parser.h index ee96c73e..3a214bef 100644 --- a/pjsip/include/pjsip/sip_auth_parser.h +++ b/pjsip/include/pjsip/sip_auth_parser.h @@ -1,87 +1,87 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_AUTH_SIP_AUTH_PARSER_H__
-#define __PJSIP_AUTH_SIP_AUTH_PARSER_H__
-
-/**
- * @file pjsip_auth_parser.h
- * @brief SIP Authorization Parser Module.
- */
-
-#include <pj/types.h>
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJSIP_AUTH_PARSER_MODULE Authorization Parser Module
- * @ingroup PJSIP_AUTH
- * @{
- */
-
-/**
- * Initialize and register authorization parser module.
- * This will register parser handler for various Authorization related headers
- * such as Authorization, WWW-Authenticate, Proxy-Authorizization, and
- * Proxy-Authenticate headers.
- *
- * @return PJ_SUCCESS or the appropriate status code.
- */
-PJ_DECL(pj_status_t) pjsip_auth_init_parser(void);
-
-/**
- * DeInitialize authorization parser module.
- */
-PJ_DECL(void) pjsip_auth_deinit_parser();
-
-
-extern const pj_str_t pjsip_USERNAME_STR,
- pjsip_REALM_STR,
- pjsip_NONCE_STR,
- pjsip_URI_STR,
- pjsip_RESPONSE_STR,
- pjsip_ALGORITHM_STR,
- pjsip_DOMAIN_STR,
- pjsip_STALE_STR,
- pjsip_QOP_STR,
- pjsip_CNONCE_STR,
- pjsip_OPAQUE_STR,
- pjsip_NC_STR,
- pjsip_TRUE_STR,
- pjsip_FALSE_STR,
- pjsip_DIGEST_STR,
- pjsip_PGP_STR,
- pjsip_MD5_STR,
- pjsip_AUTH_STR;
-/*
-extern const pj_str_t pjsip_QUOTED_TRUE_STR,
- pjsip_QUOTED_FALSE_STR,
- pjsip_QUOTED_DIGEST_STR,
- pjsip_QUOTED_PGP_STR,
- pjsip_QUOTED_MD5_STR,
- pjsip_QUOTED_AUTH_STR;
-*/
-
-/**
- * @}
- */
-
-PJ_END_DECL
-
-#endif /* __PJSIP_AUTH_SIP_AUTH_PARSER_H__ */
-
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_AUTH_SIP_AUTH_PARSER_H__ +#define __PJSIP_AUTH_SIP_AUTH_PARSER_H__ + +/** + * @file pjsip_auth_parser.h + * @brief SIP Authorization Parser Module. + */ + +#include <pj/types.h> + +PJ_BEGIN_DECL + +/** + * @defgroup PJSIP_AUTH_PARSER_MODULE Authorization Parser Module + * @ingroup PJSIP_AUTH + * @{ + */ + +/** + * Initialize and register authorization parser module. + * This will register parser handler for various Authorization related headers + * such as Authorization, WWW-Authenticate, Proxy-Authorizization, and + * Proxy-Authenticate headers. + * + * @return PJ_SUCCESS or the appropriate status code. + */ +PJ_DECL(pj_status_t) pjsip_auth_init_parser(void); + +/** + * DeInitialize authorization parser module. + */ +PJ_DECL(void) pjsip_auth_deinit_parser(); + + +extern const pj_str_t pjsip_USERNAME_STR, + pjsip_REALM_STR, + pjsip_NONCE_STR, + pjsip_URI_STR, + pjsip_RESPONSE_STR, + pjsip_ALGORITHM_STR, + pjsip_DOMAIN_STR, + pjsip_STALE_STR, + pjsip_QOP_STR, + pjsip_CNONCE_STR, + pjsip_OPAQUE_STR, + pjsip_NC_STR, + pjsip_TRUE_STR, + pjsip_FALSE_STR, + pjsip_DIGEST_STR, + pjsip_PGP_STR, + pjsip_MD5_STR, + pjsip_AUTH_STR; +/* +extern const pj_str_t pjsip_QUOTED_TRUE_STR, + pjsip_QUOTED_FALSE_STR, + pjsip_QUOTED_DIGEST_STR, + pjsip_QUOTED_PGP_STR, + pjsip_QUOTED_MD5_STR, + pjsip_QUOTED_AUTH_STR; +*/ + +/** + * @} + */ + +PJ_END_DECL + +#endif /* __PJSIP_AUTH_SIP_AUTH_PARSER_H__ */ + diff --git a/pjsip/include/pjsip/sip_config.h b/pjsip/include/pjsip/sip_config.h index 5620c33b..98441918 100644 --- a/pjsip/include/pjsip/sip_config.h +++ b/pjsip/include/pjsip/sip_config.h @@ -1,163 +1,163 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIP_CONFIG_H__
-#define __PJSIP_SIP_CONFIG_H__
-
-#include <pj/config.h>
-
-/* Endpoint. */
-#define PJSIP_MAX_TIMER_COUNT (2*PJSIP_MAX_TSX_COUNT + 2*PJSIP_MAX_DIALOG_COUNT)
-#define PJSIP_POOL_LEN_ENDPT (2048+64*PJSIP_MAX_TSX_COUNT)
-#define PJSIP_POOL_INC_ENDPT (1024)
-
-/* Transport related constants. */
-#define PJSIP_MAX_TRANSPORTS (PJ_IOQUEUE_MAX_HANDLES)
-#define PJSIP_MAX_PKT_LEN 1500
-#define PJSIP_POOL_LEN_RDATA 2500
-#define PJSIP_POOL_INC_RDATA 512
-#define PJSIP_POOL_LEN_TRANSPORT 512
-#define PJSIP_POOL_INC_TRANSPORT 512
-#define PJSIP_POOL_LEN_TDATA 2500
-#define PJSIP_POOL_INC_TDATA 512
-#define PJSIP_POOL_LEN_UA (64 + 32*PJSIP_MAX_DIALOG_COUNT)
-#define PJSIP_POOL_INC_UA 0
-#define PJSIP_TRANSPORT_CLOSE_TIMEOUT 30
-#define PJSIP_MAX_TRANSPORT_USAGE 16
-
-#define PJSIP_MAX_FORWARDS_VALUE 70
-
-#define PJSIP_RFC3261_BRANCH_ID "z9hG4bK"
-#define PJSIP_RFC3261_BRANCH_LEN 7
-
-/* Message/URL related constants. */
-#define PJSIP_MAX_CALL_ID_LEN PJ_GUID_STRING_LENGTH
-#define PJSIP_MAX_TAG_LEN PJ_GUID_STRING_LENGTH
-#define PJSIP_MAX_BRANCH_LEN (PJSIP_RFC3261_BRANCH_LEN + PJ_GUID_STRING_LENGTH)
-#define PJSIP_MAX_URL_SIZE 256
-#define PJSIP_MAX_HNAME_LEN 64
-
-/* Transction related constants. */
-#define PJSIP_MAX_TSX_COUNT (16*1024)
-#define PJSIP_POOL_LEN_TSX 1536 //768
-#define PJSIP_POOL_INC_TSX 256
-#define PJSIP_MAX_TSX_KEY_LEN (PJSIP_MAX_URL_SIZE*2)
-
-/* Dialog related constants. */
-#define PJSIP_MAX_DIALOG_COUNT (16*1024)
-#define PJSIP_POOL_LEN_DIALOG 1200
-#define PJSIP_POOL_INC_DIALOG 512
-
-/* Transport manager hash table size (must be 2^n-1). */
-#define PJSIP_TPMGR_HTABLE_SIZE 31
-
-/* Transport idle timeout before it's destroyed. */
-#define PJSIP_TRANSPORT_IDLE_TIME 30
-
-/* Max entries to process in timer heap per poll. */
-#define PJSIP_MAX_TIMED_OUT_ENTRIES 10
-
-/* Module related constants. */
-#define PJSIP_MAX_MODULE 8
-
-/*****************************************************************************
- * Default timeout settings, in miliseconds.
- */
-
-//#define PJSIP_T1_TIMEOUT 15000
-//#define PJSIP_T2_TIMEOUT 60000
-
-/* T1 timeout value. */
-#if !defined(PJSIP_T1_TIMEOUT)
-# define PJSIP_T1_TIMEOUT 500
-#endif
-
-/* T2 timeout value. */
-#if !defined(PJSIP_T2_TIMEOUT)
-# define PJSIP_T2_TIMEOUT 4000
-#endif
-
-/* Completed timer for non-INVITE */
-#if !defined(PJSIP_T4_TIMEOUT)
-# define PJSIP_T4_TIMEOUT 5000
-#endif
-
-/* Completed timer for INVITE */
-#if !defined(PJSIP_TD_TIMEOUT)
-# define PJSIP_TD_TIMEOUT 32000
-#endif
-
-
-/*****************************************************************************
- * Authorization
- */
-
-/*
- * If this flag is set, the stack will keep the Authorization/Proxy-Authorization
- * headers that are sent in a cache. Future requests with the same realm and
- * the same method will use the headers in the cache (as long as no qop is
- * required by server).
- *
- * Turning on this flag will make authorization process goes faster, but
- * will grow the memory usage undefinitely until the dialog/registration
- * session is terminated.
- *
- * Default: 1
- */
-#if !defined(PJSIP_AUTH_HEADER_CACHING)
-# define PJSIP_AUTH_HEADER_CACHING 1
-#endif
-
-/*
- * If this flag is set, the stack will proactively send Authorization/Proxy-
- * Authorization header for next requests. If next request has the same method
- * with any of previous requests, then the last header which is saved in
- * the cache will be used (if PJSIP_AUTH_CACHING is set). Otherwise a fresh
- * header will be recalculated. If a particular server has requested qop, then
- * a fresh header will always be calculated.
- *
- * If this flag is NOT set, then the stack will only send Authorization/Proxy-
- * Authorization headers when it receives 401/407 response from server.
- *
- * Turning ON this flag will grow memory usage of a dialog/registration pool
- * indefinitely until it is terminated, because the stack needs to keep the
- * last WWW-Authenticate/Proxy-Authenticate challenge.
- *
- * Default: 1
- */
-#if !defined(PJSIP_AUTH_AUTO_SEND_NEXT)
-# define PJSIP_AUTH_AUTO_SEND_NEXT 1
-#endif
-
-/*
- * Support qop="auth" directive.
- * This option also requires client to cache the last challenge offered by
- * server.
- *
- * Default: 1
- */
-#if !defined(PJSIP_AUTH_QOP_SUPPORT)
-# define PJSIP_AUTH_QOP_SUPPORT 1
-#endif
-
-
-#include <pj/config.h>
-
-
-#endif /* __PJSIP_SIP_CONFIG_H__ */
-
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIP_CONFIG_H__ +#define __PJSIP_SIP_CONFIG_H__ + +#include <pj/config.h> + +/* Endpoint. */ +#define PJSIP_MAX_TIMER_COUNT (2*PJSIP_MAX_TSX_COUNT + 2*PJSIP_MAX_DIALOG_COUNT) +#define PJSIP_POOL_LEN_ENDPT (2048+64*PJSIP_MAX_TSX_COUNT) +#define PJSIP_POOL_INC_ENDPT (1024) + +/* Transport related constants. */ +#define PJSIP_MAX_TRANSPORTS (PJ_IOQUEUE_MAX_HANDLES) +#define PJSIP_MAX_PKT_LEN 1500 +#define PJSIP_POOL_LEN_RDATA 2500 +#define PJSIP_POOL_INC_RDATA 512 +#define PJSIP_POOL_LEN_TRANSPORT 512 +#define PJSIP_POOL_INC_TRANSPORT 512 +#define PJSIP_POOL_LEN_TDATA 2500 +#define PJSIP_POOL_INC_TDATA 512 +#define PJSIP_POOL_LEN_UA (64 + 32*PJSIP_MAX_DIALOG_COUNT) +#define PJSIP_POOL_INC_UA 0 +#define PJSIP_TRANSPORT_CLOSE_TIMEOUT 30 +#define PJSIP_MAX_TRANSPORT_USAGE 16 + +#define PJSIP_MAX_FORWARDS_VALUE 70 + +#define PJSIP_RFC3261_BRANCH_ID "z9hG4bK" +#define PJSIP_RFC3261_BRANCH_LEN 7 + +/* Message/URL related constants. */ +#define PJSIP_MAX_CALL_ID_LEN PJ_GUID_STRING_LENGTH +#define PJSIP_MAX_TAG_LEN PJ_GUID_STRING_LENGTH +#define PJSIP_MAX_BRANCH_LEN (PJSIP_RFC3261_BRANCH_LEN + PJ_GUID_STRING_LENGTH) +#define PJSIP_MAX_URL_SIZE 256 +#define PJSIP_MAX_HNAME_LEN 64 + +/* Transction related constants. */ +#define PJSIP_MAX_TSX_COUNT (16*1024) +#define PJSIP_POOL_LEN_TSX 1536 //768 +#define PJSIP_POOL_INC_TSX 256 +#define PJSIP_MAX_TSX_KEY_LEN (PJSIP_MAX_URL_SIZE*2) + +/* Dialog related constants. */ +#define PJSIP_MAX_DIALOG_COUNT (16*1024) +#define PJSIP_POOL_LEN_DIALOG 1200 +#define PJSIP_POOL_INC_DIALOG 512 + +/* Transport manager hash table size (must be 2^n-1). */ +#define PJSIP_TPMGR_HTABLE_SIZE 31 + +/* Transport idle timeout before it's destroyed. */ +#define PJSIP_TRANSPORT_IDLE_TIME 30 + +/* Max entries to process in timer heap per poll. */ +#define PJSIP_MAX_TIMED_OUT_ENTRIES 10 + +/* Module related constants. */ +#define PJSIP_MAX_MODULE 8 + +/***************************************************************************** + * Default timeout settings, in miliseconds. + */ + +//#define PJSIP_T1_TIMEOUT 15000 +//#define PJSIP_T2_TIMEOUT 60000 + +/* T1 timeout value. */ +#if !defined(PJSIP_T1_TIMEOUT) +# define PJSIP_T1_TIMEOUT 500 +#endif + +/* T2 timeout value. */ +#if !defined(PJSIP_T2_TIMEOUT) +# define PJSIP_T2_TIMEOUT 4000 +#endif + +/* Completed timer for non-INVITE */ +#if !defined(PJSIP_T4_TIMEOUT) +# define PJSIP_T4_TIMEOUT 5000 +#endif + +/* Completed timer for INVITE */ +#if !defined(PJSIP_TD_TIMEOUT) +# define PJSIP_TD_TIMEOUT 32000 +#endif + + +/***************************************************************************** + * Authorization + */ + +/* + * If this flag is set, the stack will keep the Authorization/Proxy-Authorization + * headers that are sent in a cache. Future requests with the same realm and + * the same method will use the headers in the cache (as long as no qop is + * required by server). + * + * Turning on this flag will make authorization process goes faster, but + * will grow the memory usage undefinitely until the dialog/registration + * session is terminated. + * + * Default: 1 + */ +#if !defined(PJSIP_AUTH_HEADER_CACHING) +# define PJSIP_AUTH_HEADER_CACHING 1 +#endif + +/* + * If this flag is set, the stack will proactively send Authorization/Proxy- + * Authorization header for next requests. If next request has the same method + * with any of previous requests, then the last header which is saved in + * the cache will be used (if PJSIP_AUTH_CACHING is set). Otherwise a fresh + * header will be recalculated. If a particular server has requested qop, then + * a fresh header will always be calculated. + * + * If this flag is NOT set, then the stack will only send Authorization/Proxy- + * Authorization headers when it receives 401/407 response from server. + * + * Turning ON this flag will grow memory usage of a dialog/registration pool + * indefinitely until it is terminated, because the stack needs to keep the + * last WWW-Authenticate/Proxy-Authenticate challenge. + * + * Default: 1 + */ +#if !defined(PJSIP_AUTH_AUTO_SEND_NEXT) +# define PJSIP_AUTH_AUTO_SEND_NEXT 1 +#endif + +/* + * Support qop="auth" directive. + * This option also requires client to cache the last challenge offered by + * server. + * + * Default: 1 + */ +#if !defined(PJSIP_AUTH_QOP_SUPPORT) +# define PJSIP_AUTH_QOP_SUPPORT 1 +#endif + + +#include <pj/config.h> + + +#endif /* __PJSIP_SIP_CONFIG_H__ */ + diff --git a/pjsip/include/pjsip/sip_endpoint.h b/pjsip/include/pjsip/sip_endpoint.h index 37f4acee..3e0702f1 100644 --- a/pjsip/include/pjsip/sip_endpoint.h +++ b/pjsip/include/pjsip/sip_endpoint.h @@ -1,386 +1,386 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIP_ENDPOINT_H__
-#define __PJSIP_SIP_ENDPOINT_H__
-
-/**
- * @file sip_endpoint.h
- * @brief SIP Endpoint.
- */
-
-#include <pjsip/sip_transport.h>
-#include <pjsip/sip_resolve.h>
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJSIP SIP Stack Core
- * Implementation of core SIP protocol stack processing.
- */
-
-/**
- * @defgroup PJSIP_ENDPT SIP Endpoint
- * @ingroup PJSIP
- * @brief
- * Representation of SIP node instance.
- *
- * SIP Endpoint instance (pjsip_endpoint) can be viewed as the master/owner of
- * all SIP objects in an application. It performs the following roles:
- * - it manages the allocation/deallocation of memory pools for all objects.
- * - it manages listeners and transports, and how they are used by
- * transactions.
- * - it owns transaction hash table.
- * - it receives incoming messages from transport layer and automatically
- * dispatches them to the correct transaction (or create a new one).
- * - it has a single instance of timer management (timer heap).
- * - it manages modules, which is the primary means of extending the library.
- * - it provides single polling function for all objects and distributes
- * events.
- * - it provides SIP policy such as which outbound proxy to use for all
- * outgoing SIP request messages.
- * - it automatically handles incoming requests which can not be handled by
- * existing modules (such as when incoming request has unsupported method).
- * - and so on..
- *
- * Theoritically application can have multiple instances of SIP endpoint,
- * although it's not clear why application may want to do it.
- *
- * @{
- */
-
-/**
- * Create an instance of SIP endpoint from the specified pool factory.
- * The pool factory reference then will be kept by the endpoint, so that
- * future memory allocations by SIP components will be taken from the same
- * pool factory.
- *
- * @param pf Pool factory that will be used for the lifetime of
- * endpoint.
- * @param name Optional name to be specified for the endpoint.
- * If this parameter is NULL, then the name will use
- * local host name.
- * @param endpt Pointer to receive endpoint instance.
- *
- * @return PJ_SUCCESS on success.
- */
-PJ_DECL(pj_status_t) pjsip_endpt_create(pj_pool_factory *pf,
- const char *name,
- pjsip_endpoint **endpt);
-
-/**
- * Destroy endpoint instance. Application must make sure that all pending
- * transactions have been terminated properly, because this function does not
- * check for the presence of pending transactions.
- *
- * @param endpt The SIP endpoint to be destroyed.
- */
-PJ_DECL(void) pjsip_endpt_destroy(pjsip_endpoint *endpt);
-
-/**
- * Get endpoint name.
- *
- * @param endpt The SIP endpoint instance.
- *
- * @return Endpoint name, as was registered during endpoint
- * creation. The string is NULL terminated.
- */
-PJ_DECL(const pj_str_t*) pjsip_endpt_name(const pjsip_endpoint *endpt);
-
-/**
- * Poll for events. Application must call this function periodically to ensure
- * that all events from both transports and timer heap are handled in timely
- * manner. This function, like all other endpoint functions, is thread safe,
- * and application may have more than one thread concurrently calling this function.
- *
- * @param endpt The endpoint.
- * @param max_timeout Maximum time to wait for events, or NULL to wait forever
- * until event is received.
- */
-PJ_DECL(void) pjsip_endpt_handle_events( pjsip_endpoint *endpt,
- const pj_time_val *max_timeout);
-
-/**
- * Dump endpoint status to the log. This will print the status to the log
- * with log level 3.
- *
- * @param endpt The endpoint.
- * @param detail If non zero, then it will dump a detailed output.
- * BEWARE that this option may crash the system because
- * it tries to access all memory pools.
- */
-PJ_DECL(void) pjsip_endpt_dump( pjsip_endpoint *endpt, pj_bool_t detail );
-
-/**
- * Create pool from the endpoint. All SIP components should allocate their
- * memory pool by calling this function, to make sure that the pools are
- * allocated from the same pool factory. This function, like all other endpoint
- * functions, is thread safe.
- *
- * @param endpt The SIP endpoint.
- * @param pool_name Name to be assigned to the pool.
- * @param initial The initial size of the pool.
- * @param increment The resize size.
- * @return Memory pool, or NULL on failure.
- *
- * @see pj_pool_create
- */
-PJ_DECL(pj_pool_t*) pjsip_endpt_create_pool( pjsip_endpoint *endpt,
- const char *pool_name,
- pj_size_t initial,
- pj_size_t increment );
-
-/**
- * Return back pool to endpoint to be released back to the pool factory.
- * This function, like all other endpoint functions, is thread safe.
- *
- * @param endpt The endpoint.
- * @param pool The pool to be destroyed.
- */
-PJ_DECL(void) pjsip_endpt_destroy_pool( pjsip_endpoint *endpt,
- pj_pool_t *pool );
-
-/**
- * Schedule timer to endpoint's timer heap. Application must poll the endpoint
- * periodically (by calling #pjsip_endpt_handle_events) to ensure that the
- * timer events are handled in timely manner. When the timeout for the timer
- * has elapsed, the callback specified in the entry argument will be called.
- * This function, like all other endpoint functions, is thread safe.
- *
- * @param endpt The endpoint.
- * @param entry The timer entry.
- * @param delay The relative delay of the timer.
- * @return PJ_OK (zero) if successfull.
- */
-PJ_DECL(pj_status_t) pjsip_endpt_schedule_timer( pjsip_endpoint *endpt,
- pj_timer_entry *entry,
- const pj_time_val *delay );
-
-/**
- * Cancel the previously registered timer.
- * This function, like all other endpoint functions, is thread safe.
- *
- * @param endpt The endpoint.
- * @param entry The timer entry previously registered.
- */
-PJ_DECL(void) pjsip_endpt_cancel_timer( pjsip_endpoint *endpt,
- pj_timer_entry *entry );
-
-/**
- * Create a new transaction. After creating the transaction, application MUST
- * initialize the transaction as either UAC or UAS (by calling
- * #pjsip_tsx_init_uac or #pjsip_tsx_init_uas), then must register the
- * transaction to endpoint with #pjsip_endpt_register_tsx.
- * This function, like all other endpoint functions, is thread safe.
- *
- * @param endpt The SIP endpoint.
- * @param p_tsx Pointer to receive the transaction.
- *
- * @return PJ_SUCCESS or the appropriate error code.
- */
-PJ_DECL(pj_status_t) pjsip_endpt_create_tsx(pjsip_endpoint *endpt,
- pjsip_transaction **p_tsx);
-
-/**
- * Register the transaction to the endpoint's transaction table.
- * Before the transaction is registered, it must have been initialized as
- * either UAS or UAC by calling #pjsip_tsx_init_uac or #pjsip_tsx_init_uas.
- * This function, like all other endpoint functions, is thread safe.
- *
- * @param endpt The SIP endpoint.
- * @param tsx The transaction.
- */
-PJ_DECL(void) pjsip_endpt_register_tsx( pjsip_endpoint *endpt,
- pjsip_transaction *tsx);
-
-/**
- * Forcefull destroy the transaction.
- * The only time where application needs to call this function is when the
- * transaction fails to initialize in #pjsip_tsx_init_uac or
- * #pjsip_tsx_init_uas. For other cases. the transaction will be destroyed
- * automaticly by endpoint.
- *
- * @param endpt The endpoint.
- * @param tsx The transaction to destroy.
- */
-PJ_DECL(void) pjsip_endpt_destroy_tsx( pjsip_endpoint *endpt,
- pjsip_transaction *tsx);
-
-/**
- * Create a new transmit data buffer.
- * This function, like all other endpoint functions, is thread safe.
- *
- * @param endpt The endpoint.
- * @param p_tdata Pointer to receive transmit data buffer.
- *
- * @return PJ_SUCCESS or the appropriate error code.
- */
-PJ_DECL(pj_status_t) pjsip_endpt_create_tdata( pjsip_endpoint *endpt,
- pjsip_tx_data **p_tdata);
-
-/**
- * Asynchronously resolve a SIP target host or domain according to rule
- * specified in RFC 3263 (Locating SIP Servers). When the resolving operation
- * has completed, the callback will be called.
- *
- * Note: at the moment we don't have implementation of RFC 3263 yet!
- *
- * @param resolver The resolver engine.
- * @param pool The pool to allocate resolver job.
- * @param target The target specification to be resolved.
- * @param token A user defined token to be passed back to callback function.
- * @param cb The callback function.
- */
-PJ_DECL(void) pjsip_endpt_resolve( pjsip_endpoint *endpt,
- pj_pool_t *pool,
- pjsip_host_port *target,
- void *token,
- pjsip_resolver_callback *cb);
-
-/**
- * Get transport manager instance.
- *
- * @param endpt The endpoint.
- *
- * @return Transport manager instance.
- */
-PJ_DECL(pjsip_tpmgr*) pjsip_endpt_get_tpmgr(pjsip_endpoint *endpt);
-
-/**
- * Get ioqueue instance.
- *
- * @param endpt The endpoint.
- *
- * @return The ioqueue.
- */
-PJ_DECL(pj_ioqueue_t*) pjsip_endpt_get_ioqueue(pjsip_endpoint *endpt);
-
-/**
- * Find a SIP transport suitable for sending SIP message to the specified
- * address. This function will complete asynchronously when the transport is
- * ready (for example, when TCP socket is connected), and when it completes,
- * the callback will be called with the status of the operation.
- *
- * @see pjsip_transport_get
- */
-PJ_DECL(pj_status_t) pjsip_endpt_alloc_transport( pjsip_endpoint *endpt,
- pjsip_transport_type_e type,
- const pj_sockaddr_in *remote,
- pjsip_transport **p_transport);
-
-/**
- * Get additional headers to be put in outgoing request message.
- * This function is normally called by transaction layer when sending outgoing
- * requests.
- *
- * @param endpt The endpoint.
- *
- * @return List of additional headers to be put in outgoing requests.
- */
-PJ_DECL(const pjsip_hdr*) pjsip_endpt_get_request_headers(pjsip_endpoint *endpt);
-
-/**
- * Get "Allow" header from endpoint. The endpoint builds the "Allow" header
- * from the list of methods supported by modules.
- *
- * @param endpt The endpoint.
- *
- * @return "Allow" header, or NULL if endpoint doesn't have "Allow" header.
- */
-PJ_DECL(const pjsip_allow_hdr*) pjsip_endpt_get_allow_hdr( pjsip_endpoint *endpt );
-
-
-/**
- * Find transaction in endpoint's transaction table by the transaction's key.
- * This function normally is only used by modules. The key for a transaction
- * can be created by calling #pjsip_tsx_create_key.
- *
- * @param endpt The endpoint instance.
- * @param key Transaction key, as created with #pjsip_tsx_create_key.
- *
- * @return The transaction, or NULL if it's not found.
- */
-PJ_DECL(pjsip_transaction*) pjsip_endpt_find_tsx( pjsip_endpoint *endpt,
- const pj_str_t *key );
-
-/**
- * Set list of SIP proxies to be visited for all outbound request messages.
- * Application can call this function to specify how outgoing request messages
- * should be routed. For example, if outgoing requests should go through an
- * outbound proxy, then application can specify the URL of the proxy when
- * calling this function. More than one proxy can be specified, and the
- * order of which proxy is specified when calling this function specifies
- * the order of which proxy will be visited first by the request messages.
- *
- * @param endpt The endpoint instance.
- * @param url_cnt Number of proxies/URLs in the array.
- * @param url Array of proxy URL, which specifies the order of which
- * proxy will be visited first (e.g. url[0] will be visited
- * before url[1]).
- *
- * @return Zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_endpt_set_proxies( pjsip_endpoint *endpt,
- int url_cnt, const pj_str_t url[]);
-
-/**
- * Get the list of "Route" header that are configured for this endpoint.
- * The "Route" header specifies how outbound request messages will be sent,
- * and is built when application sets the outbound proxy.
- *
- * @param endpt The endpoint instance.
- *
- * @return List of "Route" header.
- */
-PJ_DECL(const pjsip_route_hdr*) pjsip_endpt_get_routing( pjsip_endpoint *endpt );
-
-/**
- * Log an error.
- */
-PJ_DECL(void) pjsip_endpt_log_error( pjsip_endpoint *endpt,
- const char *sender,
- pj_status_t error_code,
- const char *format,
- ... );
-
-#define PJSIP_ENDPT_LOG_ERROR(expr) \
- pjsip_endpt_log_error expr
-
-#define PJSIP_ENDPT_TRACE(tracing,expr) \
- do { \
- if ((tracing)) \
- PJ_LOG(4,expr); \
- } while (0)
-
-/**
- * @}
- */
-
-/*
- * Internal functions.
- */
-/*
- * Receive transaction events from transactions and put in the event queue
- * to be processed later.
- */
-void pjsip_endpt_send_tsx_event( pjsip_endpoint *endpt, pjsip_event *evt );
-
-PJ_END_DECL
-
-#endif /* __PJSIP_SIP_ENDPOINT_H__ */
-
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIP_ENDPOINT_H__ +#define __PJSIP_SIP_ENDPOINT_H__ + +/** + * @file sip_endpoint.h + * @brief SIP Endpoint. + */ + +#include <pjsip/sip_transport.h> +#include <pjsip/sip_resolve.h> + +PJ_BEGIN_DECL + +/** + * @defgroup PJSIP SIP Stack Core + * Implementation of core SIP protocol stack processing. + */ + +/** + * @defgroup PJSIP_ENDPT SIP Endpoint + * @ingroup PJSIP + * @brief + * Representation of SIP node instance. + * + * SIP Endpoint instance (pjsip_endpoint) can be viewed as the master/owner of + * all SIP objects in an application. It performs the following roles: + * - it manages the allocation/deallocation of memory pools for all objects. + * - it manages listeners and transports, and how they are used by + * transactions. + * - it owns transaction hash table. + * - it receives incoming messages from transport layer and automatically + * dispatches them to the correct transaction (or create a new one). + * - it has a single instance of timer management (timer heap). + * - it manages modules, which is the primary means of extending the library. + * - it provides single polling function for all objects and distributes + * events. + * - it provides SIP policy such as which outbound proxy to use for all + * outgoing SIP request messages. + * - it automatically handles incoming requests which can not be handled by + * existing modules (such as when incoming request has unsupported method). + * - and so on.. + * + * Theoritically application can have multiple instances of SIP endpoint, + * although it's not clear why application may want to do it. + * + * @{ + */ + +/** + * Create an instance of SIP endpoint from the specified pool factory. + * The pool factory reference then will be kept by the endpoint, so that + * future memory allocations by SIP components will be taken from the same + * pool factory. + * + * @param pf Pool factory that will be used for the lifetime of + * endpoint. + * @param name Optional name to be specified for the endpoint. + * If this parameter is NULL, then the name will use + * local host name. + * @param endpt Pointer to receive endpoint instance. + * + * @return PJ_SUCCESS on success. + */ +PJ_DECL(pj_status_t) pjsip_endpt_create(pj_pool_factory *pf, + const char *name, + pjsip_endpoint **endpt); + +/** + * Destroy endpoint instance. Application must make sure that all pending + * transactions have been terminated properly, because this function does not + * check for the presence of pending transactions. + * + * @param endpt The SIP endpoint to be destroyed. + */ +PJ_DECL(void) pjsip_endpt_destroy(pjsip_endpoint *endpt); + +/** + * Get endpoint name. + * + * @param endpt The SIP endpoint instance. + * + * @return Endpoint name, as was registered during endpoint + * creation. The string is NULL terminated. + */ +PJ_DECL(const pj_str_t*) pjsip_endpt_name(const pjsip_endpoint *endpt); + +/** + * Poll for events. Application must call this function periodically to ensure + * that all events from both transports and timer heap are handled in timely + * manner. This function, like all other endpoint functions, is thread safe, + * and application may have more than one thread concurrently calling this function. + * + * @param endpt The endpoint. + * @param max_timeout Maximum time to wait for events, or NULL to wait forever + * until event is received. + */ +PJ_DECL(void) pjsip_endpt_handle_events( pjsip_endpoint *endpt, + const pj_time_val *max_timeout); + +/** + * Dump endpoint status to the log. This will print the status to the log + * with log level 3. + * + * @param endpt The endpoint. + * @param detail If non zero, then it will dump a detailed output. + * BEWARE that this option may crash the system because + * it tries to access all memory pools. + */ +PJ_DECL(void) pjsip_endpt_dump( pjsip_endpoint *endpt, pj_bool_t detail ); + +/** + * Create pool from the endpoint. All SIP components should allocate their + * memory pool by calling this function, to make sure that the pools are + * allocated from the same pool factory. This function, like all other endpoint + * functions, is thread safe. + * + * @param endpt The SIP endpoint. + * @param pool_name Name to be assigned to the pool. + * @param initial The initial size of the pool. + * @param increment The resize size. + * @return Memory pool, or NULL on failure. + * + * @see pj_pool_create + */ +PJ_DECL(pj_pool_t*) pjsip_endpt_create_pool( pjsip_endpoint *endpt, + const char *pool_name, + pj_size_t initial, + pj_size_t increment ); + +/** + * Return back pool to endpoint to be released back to the pool factory. + * This function, like all other endpoint functions, is thread safe. + * + * @param endpt The endpoint. + * @param pool The pool to be destroyed. + */ +PJ_DECL(void) pjsip_endpt_destroy_pool( pjsip_endpoint *endpt, + pj_pool_t *pool ); + +/** + * Schedule timer to endpoint's timer heap. Application must poll the endpoint + * periodically (by calling #pjsip_endpt_handle_events) to ensure that the + * timer events are handled in timely manner. When the timeout for the timer + * has elapsed, the callback specified in the entry argument will be called. + * This function, like all other endpoint functions, is thread safe. + * + * @param endpt The endpoint. + * @param entry The timer entry. + * @param delay The relative delay of the timer. + * @return PJ_OK (zero) if successfull. + */ +PJ_DECL(pj_status_t) pjsip_endpt_schedule_timer( pjsip_endpoint *endpt, + pj_timer_entry *entry, + const pj_time_val *delay ); + +/** + * Cancel the previously registered timer. + * This function, like all other endpoint functions, is thread safe. + * + * @param endpt The endpoint. + * @param entry The timer entry previously registered. + */ +PJ_DECL(void) pjsip_endpt_cancel_timer( pjsip_endpoint *endpt, + pj_timer_entry *entry ); + +/** + * Create a new transaction. After creating the transaction, application MUST + * initialize the transaction as either UAC or UAS (by calling + * #pjsip_tsx_init_uac or #pjsip_tsx_init_uas), then must register the + * transaction to endpoint with #pjsip_endpt_register_tsx. + * This function, like all other endpoint functions, is thread safe. + * + * @param endpt The SIP endpoint. + * @param p_tsx Pointer to receive the transaction. + * + * @return PJ_SUCCESS or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsip_endpt_create_tsx(pjsip_endpoint *endpt, + pjsip_transaction **p_tsx); + +/** + * Register the transaction to the endpoint's transaction table. + * Before the transaction is registered, it must have been initialized as + * either UAS or UAC by calling #pjsip_tsx_init_uac or #pjsip_tsx_init_uas. + * This function, like all other endpoint functions, is thread safe. + * + * @param endpt The SIP endpoint. + * @param tsx The transaction. + */ +PJ_DECL(void) pjsip_endpt_register_tsx( pjsip_endpoint *endpt, + pjsip_transaction *tsx); + +/** + * Forcefull destroy the transaction. + * The only time where application needs to call this function is when the + * transaction fails to initialize in #pjsip_tsx_init_uac or + * #pjsip_tsx_init_uas. For other cases. the transaction will be destroyed + * automaticly by endpoint. + * + * @param endpt The endpoint. + * @param tsx The transaction to destroy. + */ +PJ_DECL(void) pjsip_endpt_destroy_tsx( pjsip_endpoint *endpt, + pjsip_transaction *tsx); + +/** + * Create a new transmit data buffer. + * This function, like all other endpoint functions, is thread safe. + * + * @param endpt The endpoint. + * @param p_tdata Pointer to receive transmit data buffer. + * + * @return PJ_SUCCESS or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsip_endpt_create_tdata( pjsip_endpoint *endpt, + pjsip_tx_data **p_tdata); + +/** + * Asynchronously resolve a SIP target host or domain according to rule + * specified in RFC 3263 (Locating SIP Servers). When the resolving operation + * has completed, the callback will be called. + * + * Note: at the moment we don't have implementation of RFC 3263 yet! + * + * @param resolver The resolver engine. + * @param pool The pool to allocate resolver job. + * @param target The target specification to be resolved. + * @param token A user defined token to be passed back to callback function. + * @param cb The callback function. + */ +PJ_DECL(void) pjsip_endpt_resolve( pjsip_endpoint *endpt, + pj_pool_t *pool, + pjsip_host_port *target, + void *token, + pjsip_resolver_callback *cb); + +/** + * Get transport manager instance. + * + * @param endpt The endpoint. + * + * @return Transport manager instance. + */ +PJ_DECL(pjsip_tpmgr*) pjsip_endpt_get_tpmgr(pjsip_endpoint *endpt); + +/** + * Get ioqueue instance. + * + * @param endpt The endpoint. + * + * @return The ioqueue. + */ +PJ_DECL(pj_ioqueue_t*) pjsip_endpt_get_ioqueue(pjsip_endpoint *endpt); + +/** + * Find a SIP transport suitable for sending SIP message to the specified + * address. This function will complete asynchronously when the transport is + * ready (for example, when TCP socket is connected), and when it completes, + * the callback will be called with the status of the operation. + * + * @see pjsip_transport_get + */ +PJ_DECL(pj_status_t) pjsip_endpt_alloc_transport( pjsip_endpoint *endpt, + pjsip_transport_type_e type, + const pj_sockaddr_in *remote, + pjsip_transport **p_transport); + +/** + * Get additional headers to be put in outgoing request message. + * This function is normally called by transaction layer when sending outgoing + * requests. + * + * @param endpt The endpoint. + * + * @return List of additional headers to be put in outgoing requests. + */ +PJ_DECL(const pjsip_hdr*) pjsip_endpt_get_request_headers(pjsip_endpoint *endpt); + +/** + * Get "Allow" header from endpoint. The endpoint builds the "Allow" header + * from the list of methods supported by modules. + * + * @param endpt The endpoint. + * + * @return "Allow" header, or NULL if endpoint doesn't have "Allow" header. + */ +PJ_DECL(const pjsip_allow_hdr*) pjsip_endpt_get_allow_hdr( pjsip_endpoint *endpt ); + + +/** + * Find transaction in endpoint's transaction table by the transaction's key. + * This function normally is only used by modules. The key for a transaction + * can be created by calling #pjsip_tsx_create_key. + * + * @param endpt The endpoint instance. + * @param key Transaction key, as created with #pjsip_tsx_create_key. + * + * @return The transaction, or NULL if it's not found. + */ +PJ_DECL(pjsip_transaction*) pjsip_endpt_find_tsx( pjsip_endpoint *endpt, + const pj_str_t *key ); + +/** + * Set list of SIP proxies to be visited for all outbound request messages. + * Application can call this function to specify how outgoing request messages + * should be routed. For example, if outgoing requests should go through an + * outbound proxy, then application can specify the URL of the proxy when + * calling this function. More than one proxy can be specified, and the + * order of which proxy is specified when calling this function specifies + * the order of which proxy will be visited first by the request messages. + * + * @param endpt The endpoint instance. + * @param url_cnt Number of proxies/URLs in the array. + * @param url Array of proxy URL, which specifies the order of which + * proxy will be visited first (e.g. url[0] will be visited + * before url[1]). + * + * @return Zero on success. + */ +PJ_DECL(pj_status_t) pjsip_endpt_set_proxies( pjsip_endpoint *endpt, + int url_cnt, const pj_str_t url[]); + +/** + * Get the list of "Route" header that are configured for this endpoint. + * The "Route" header specifies how outbound request messages will be sent, + * and is built when application sets the outbound proxy. + * + * @param endpt The endpoint instance. + * + * @return List of "Route" header. + */ +PJ_DECL(const pjsip_route_hdr*) pjsip_endpt_get_routing( pjsip_endpoint *endpt ); + +/** + * Log an error. + */ +PJ_DECL(void) pjsip_endpt_log_error( pjsip_endpoint *endpt, + const char *sender, + pj_status_t error_code, + const char *format, + ... ); + +#define PJSIP_ENDPT_LOG_ERROR(expr) \ + pjsip_endpt_log_error expr + +#define PJSIP_ENDPT_TRACE(tracing,expr) \ + do { \ + if ((tracing)) \ + PJ_LOG(4,expr); \ + } while (0) + +/** + * @} + */ + +/* + * Internal functions. + */ +/* + * Receive transaction events from transactions and put in the event queue + * to be processed later. + */ +void pjsip_endpt_send_tsx_event( pjsip_endpoint *endpt, pjsip_event *evt ); + +PJ_END_DECL + +#endif /* __PJSIP_SIP_ENDPOINT_H__ */ + diff --git a/pjsip/include/pjsip/sip_errno.h b/pjsip/include/pjsip/sip_errno.h index 2c8e6764..eefda673 100644 --- a/pjsip/include/pjsip/sip_errno.h +++ b/pjsip/include/pjsip/sip_errno.h @@ -1,228 +1,228 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIP_ERRNO_H__
-#define __PJSIP_SIP_ERRNO_H__
-
-#include <pj/errno.h>
-
-PJ_BEGIN_DECL
-
-/*
- * PJSIP error codes occupies 170000 - 219000, and mapped as follows:
- * - 170100 - 170799: mapped to SIP status code in response msg.
- * - 171000 - 171999: mapped to errors generated from PJSIP core.
- */
-
-/**
- * Get error message for the specified error code.
- *
- * @param status The error code.
- * @param buffer The buffer where to put the error message.
- * @param bufsize Size of the buffer.
- *
- * @return The error message as NULL terminated string,
- * wrapped with pj_str_t.
- */
-PJ_DECL(pj_str_t) pjsip_strerror( pj_status_t status, char *buffer,
- pj_size_t bufsize);
-
-/**
- * Start of error code relative to PJ_ERRNO_START_USER.
- */
-#define PJSIP_ERRNO_START (PJ_ERRNO_START_USER)
-
-/**
- * Create error value from SIP status code.
- * @param code SIP status code.
- * @return Error code in pj_status_t namespace.
- */
-#define PJSIP_ERRNO_FROM_SIP_STATUS(code) (PJSIP_ERRNO_START+code)
-
-/**
- * Get SIP status code from error value.
- * If conversion to SIP status code is not available, a SIP status code
- * 599 will be returned.
- *
- * @param status Error code in pj_status_t namespace.
- * @return SIP status code.
- */
-#define PJSIP_ERRNO_TO_SIP_STATUS(status) \
- ((status>=PJSIP_ERRNO_FROM_SIP_STATUS(100) && \
- status<PJSIP_ERRNO_FROM_SIP_STATUS(800)) ? \
- status-PJSIP_ERRNO_FROM_SIP_STATUS(0) : 599)
-
-
-/**
- * Start of PJSIP generated error code values.
- */
-#define PJSIP_ERRNO_START_PJSIP (PJSIP_ERRNO_START + 1000)
-
-/************************************************************
- * GENERIC SIP ERRORS
- ***********************************************************/
-/**
- * @hideinitializer
- * SIP object is busy.
- */
-#define PJSIP_EBUSY (PJSIP_ERRNO_START_PJSIP + 1) /* 171001 */
-/**
- * @hideinitializer
- * SIP object with the same type already exists.
- */
-#define PJSIP_ETYPEEXISTS (PJSIP_ERRNO_START_PJSIP + 2) /* 171002 */
-
-
-/************************************************************
- * MESSAGING ERRORS
- ***********************************************************/
-/**
- * @hideinitializer
- * Invalid message (syntax error)
- */
-#define PJSIP_EINVALIDMSG (PJSIP_ERRNO_START_PJSIP + 20) /* 171020 */
-/**
- * @hideinitializer
- * Unsupported URL scheme.
- */
-#define PJSIP_EINVALIDSCHEME (PJSIP_ERRNO_START_PJSIP + 21) /* 171021 */
-/**
- * @hideinitializer
- * Message too long. See also PJSIP_ERXOVERFLOW.
- */
-#define PJSIP_EMSGTOOLONG (PJSIP_ERRNO_START_PJSIP + 22) /* 171022 */
-/**
- * @hideinitializer
- * Message not completely received.
- */
-#define PJSIP_EPARTIALMSG (PJSIP_ERRNO_START_PJSIP + 23) /* 171023 */
-/**
- * @hideinitializer
- * Missing required header(s).
- */
-#define PJSIP_EMISSINGHDR (PJSIP_ERRNO_START_PJSIP + 24) /* 171024 */
-/**
- * @hideinitializer
- * Invalid Via header in response (sent-by, etc).
- */
-#define PJSIP_EINVALIDVIA (PJSIP_ERRNO_START_PJSIP + 25) /* 171025 */
-/**
- * @hideinitializer
- * Multiple Via headers in response.
- */
-#define PJSIP_EMULTIPLEVIA (PJSIP_ERRNO_START_PJSIP + 26) /* 171026 */
-
-/************************************************************
- * TRANSPORT ERRORS
- ***********************************************************/
-/**
- * @hideinitializer
- * Unsupported transport type.
- */
-#define PJSIP_EUNSUPTRANSPORT (PJSIP_ERRNO_START_PJSIP + 40) /* 171040 */
-/**
- * @hideinitializer
- * Buffer is being sent, operation still pending.
- */
-#define PJSIP_EPENDINGTX (PJSIP_ERRNO_START_PJSIP + 41) /* 171041 */
-/**
- * @hideinitializer
- * Rx buffer overflow. See also PJSIP_EMSGTOOLONG.
- */
-#define PJSIP_ERXOVERFLOW (PJSIP_ERRNO_START_PJSIP + 42)/* 171042 */
-
-
-/************************************************************
- * TRANSACTION ERRORS
- ***********************************************************/
-/**
- * @hideinitializer
- * Transaction has just been destroyed.
- */
-#define PJSIP_ETSXDESTROYED (PJSIP_ERRNO_START_PJSIP + 60) /* 171060 */
-
-
-/************************************************************
- * URI COMPARISON RESULTS
- ***********************************************************/
-/**
- * @hideinitializer
- * Scheme mismatch.
- */
-#define PJSIP_ECMPSCHEME (PJSIP_ERRNO_START_PJSIP + 80) /* 171080 */
-/**
- * @hideinitializer
- * User part mismatch.
- */
-#define PJSIP_ECMPUSER (PJSIP_ERRNO_START_PJSIP + 81) /* 171081 */
-/**
- * @hideinitializer
- * Password part mismatch.
- */
-#define PJSIP_ECMPPASSWD (PJSIP_ERRNO_START_PJSIP + 82) /* 171082 */
-/**
- * @hideinitializer
- * Host part mismatch.
- */
-#define PJSIP_ECMPHOST (PJSIP_ERRNO_START_PJSIP + 83) /* 171083 */
-/**
- * @hideinitializer
- * Port part mismatch.
- */
-#define PJSIP_ECMPPORT (PJSIP_ERRNO_START_PJSIP + 84) /* 171084 */
-/**
- * @hideinitializer
- * Transport parameter part mismatch.
- */
-#define PJSIP_ECMPTRANSPORTPRM (PJSIP_ERRNO_START_PJSIP + 85) /* 171085 */
-/**
- * @hideinitializer
- * TTL parameter part mismatch.
- */
-#define PJSIP_ECMPTTLPARAM (PJSIP_ERRNO_START_PJSIP + 86) /* 171086 */
-/**
- * @hideinitializer
- * User parameter part mismatch.
- */
-#define PJSIP_ECMPUSERPARAM (PJSIP_ERRNO_START_PJSIP + 87) /* 171087 */
-/**
- * @hideinitializer
- * Method parameter part mismatch.
- */
-#define PJSIP_ECMPMETHODPARAM (PJSIP_ERRNO_START_PJSIP + 88) /* 171088 */
-/**
- * @hideinitializer
- * Maddr parameter part mismatch.
- */
-#define PJSIP_ECMPMADDRPARAM (PJSIP_ERRNO_START_PJSIP + 89) /* 171089 */
-/**
- * @hideinitializer
- * Parameter part in other_param mismatch.
- */
-#define PJSIP_ECMPOTHERPARAM (PJSIP_ERRNO_START_PJSIP + 90) /* 171090 */
-/**
- * @hideinitializer
- * Parameter part in header_param mismatch.
- */
-#define PJSIP_ECMPHEADERPARAM (PJSIP_ERRNO_START_PJSIP + 91) /* 171091 */
-
-
-
-PJ_END_DECL
-
-#endif /* __PJSIP_SIP_ERRNO_H__ */
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIP_ERRNO_H__ +#define __PJSIP_SIP_ERRNO_H__ + +#include <pj/errno.h> + +PJ_BEGIN_DECL + +/* + * PJSIP error codes occupies 170000 - 219000, and mapped as follows: + * - 170100 - 170799: mapped to SIP status code in response msg. + * - 171000 - 171999: mapped to errors generated from PJSIP core. + */ + +/** + * Get error message for the specified error code. + * + * @param status The error code. + * @param buffer The buffer where to put the error message. + * @param bufsize Size of the buffer. + * + * @return The error message as NULL terminated string, + * wrapped with pj_str_t. + */ +PJ_DECL(pj_str_t) pjsip_strerror( pj_status_t status, char *buffer, + pj_size_t bufsize); + +/** + * Start of error code relative to PJ_ERRNO_START_USER. + */ +#define PJSIP_ERRNO_START (PJ_ERRNO_START_USER) + +/** + * Create error value from SIP status code. + * @param code SIP status code. + * @return Error code in pj_status_t namespace. + */ +#define PJSIP_ERRNO_FROM_SIP_STATUS(code) (PJSIP_ERRNO_START+code) + +/** + * Get SIP status code from error value. + * If conversion to SIP status code is not available, a SIP status code + * 599 will be returned. + * + * @param status Error code in pj_status_t namespace. + * @return SIP status code. + */ +#define PJSIP_ERRNO_TO_SIP_STATUS(status) \ + ((status>=PJSIP_ERRNO_FROM_SIP_STATUS(100) && \ + status<PJSIP_ERRNO_FROM_SIP_STATUS(800)) ? \ + status-PJSIP_ERRNO_FROM_SIP_STATUS(0) : 599) + + +/** + * Start of PJSIP generated error code values. + */ +#define PJSIP_ERRNO_START_PJSIP (PJSIP_ERRNO_START + 1000) + +/************************************************************ + * GENERIC SIP ERRORS + ***********************************************************/ +/** + * @hideinitializer + * SIP object is busy. + */ +#define PJSIP_EBUSY (PJSIP_ERRNO_START_PJSIP + 1) /* 171001 */ +/** + * @hideinitializer + * SIP object with the same type already exists. + */ +#define PJSIP_ETYPEEXISTS (PJSIP_ERRNO_START_PJSIP + 2) /* 171002 */ + + +/************************************************************ + * MESSAGING ERRORS + ***********************************************************/ +/** + * @hideinitializer + * Invalid message (syntax error) + */ +#define PJSIP_EINVALIDMSG (PJSIP_ERRNO_START_PJSIP + 20) /* 171020 */ +/** + * @hideinitializer + * Unsupported URL scheme. + */ +#define PJSIP_EINVALIDSCHEME (PJSIP_ERRNO_START_PJSIP + 21) /* 171021 */ +/** + * @hideinitializer + * Message too long. See also PJSIP_ERXOVERFLOW. + */ +#define PJSIP_EMSGTOOLONG (PJSIP_ERRNO_START_PJSIP + 22) /* 171022 */ +/** + * @hideinitializer + * Message not completely received. + */ +#define PJSIP_EPARTIALMSG (PJSIP_ERRNO_START_PJSIP + 23) /* 171023 */ +/** + * @hideinitializer + * Missing required header(s). + */ +#define PJSIP_EMISSINGHDR (PJSIP_ERRNO_START_PJSIP + 24) /* 171024 */ +/** + * @hideinitializer + * Invalid Via header in response (sent-by, etc). + */ +#define PJSIP_EINVALIDVIA (PJSIP_ERRNO_START_PJSIP + 25) /* 171025 */ +/** + * @hideinitializer + * Multiple Via headers in response. + */ +#define PJSIP_EMULTIPLEVIA (PJSIP_ERRNO_START_PJSIP + 26) /* 171026 */ + +/************************************************************ + * TRANSPORT ERRORS + ***********************************************************/ +/** + * @hideinitializer + * Unsupported transport type. + */ +#define PJSIP_EUNSUPTRANSPORT (PJSIP_ERRNO_START_PJSIP + 40) /* 171040 */ +/** + * @hideinitializer + * Buffer is being sent, operation still pending. + */ +#define PJSIP_EPENDINGTX (PJSIP_ERRNO_START_PJSIP + 41) /* 171041 */ +/** + * @hideinitializer + * Rx buffer overflow. See also PJSIP_EMSGTOOLONG. + */ +#define PJSIP_ERXOVERFLOW (PJSIP_ERRNO_START_PJSIP + 42)/* 171042 */ + + +/************************************************************ + * TRANSACTION ERRORS + ***********************************************************/ +/** + * @hideinitializer + * Transaction has just been destroyed. + */ +#define PJSIP_ETSXDESTROYED (PJSIP_ERRNO_START_PJSIP + 60) /* 171060 */ + + +/************************************************************ + * URI COMPARISON RESULTS + ***********************************************************/ +/** + * @hideinitializer + * Scheme mismatch. + */ +#define PJSIP_ECMPSCHEME (PJSIP_ERRNO_START_PJSIP + 80) /* 171080 */ +/** + * @hideinitializer + * User part mismatch. + */ +#define PJSIP_ECMPUSER (PJSIP_ERRNO_START_PJSIP + 81) /* 171081 */ +/** + * @hideinitializer + * Password part mismatch. + */ +#define PJSIP_ECMPPASSWD (PJSIP_ERRNO_START_PJSIP + 82) /* 171082 */ +/** + * @hideinitializer + * Host part mismatch. + */ +#define PJSIP_ECMPHOST (PJSIP_ERRNO_START_PJSIP + 83) /* 171083 */ +/** + * @hideinitializer + * Port part mismatch. + */ +#define PJSIP_ECMPPORT (PJSIP_ERRNO_START_PJSIP + 84) /* 171084 */ +/** + * @hideinitializer + * Transport parameter part mismatch. + */ +#define PJSIP_ECMPTRANSPORTPRM (PJSIP_ERRNO_START_PJSIP + 85) /* 171085 */ +/** + * @hideinitializer + * TTL parameter part mismatch. + */ +#define PJSIP_ECMPTTLPARAM (PJSIP_ERRNO_START_PJSIP + 86) /* 171086 */ +/** + * @hideinitializer + * User parameter part mismatch. + */ +#define PJSIP_ECMPUSERPARAM (PJSIP_ERRNO_START_PJSIP + 87) /* 171087 */ +/** + * @hideinitializer + * Method parameter part mismatch. + */ +#define PJSIP_ECMPMETHODPARAM (PJSIP_ERRNO_START_PJSIP + 88) /* 171088 */ +/** + * @hideinitializer + * Maddr parameter part mismatch. + */ +#define PJSIP_ECMPMADDRPARAM (PJSIP_ERRNO_START_PJSIP + 89) /* 171089 */ +/** + * @hideinitializer + * Parameter part in other_param mismatch. + */ +#define PJSIP_ECMPOTHERPARAM (PJSIP_ERRNO_START_PJSIP + 90) /* 171090 */ +/** + * @hideinitializer + * Parameter part in header_param mismatch. + */ +#define PJSIP_ECMPHEADERPARAM (PJSIP_ERRNO_START_PJSIP + 91) /* 171091 */ + + + +PJ_END_DECL + +#endif /* __PJSIP_SIP_ERRNO_H__ */ diff --git a/pjsip/include/pjsip/sip_event.h b/pjsip/include/pjsip/sip_event.h index e828ae96..22b00727 100644 --- a/pjsip/include/pjsip/sip_event.h +++ b/pjsip/include/pjsip/sip_event.h @@ -1,310 +1,310 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIP_EVENT_H__
-#define __PJSIP_SIP_EVENT_H__
-
-/**
- * @file sip_event.h
- * @brief SIP Event
- */
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJSIP_EVENT SIP Event
- * @ingroup PJSIP
- * @{
- */
-#include <pj/types.h>
-
-
-/**
- * Event IDs.
- */
-typedef enum pjsip_event_id_e
-{
- /** Unidentified event. */
- PJSIP_EVENT_UNKNOWN,
-
- /** Timer event, normally only used internally in transaction. */
- PJSIP_EVENT_TIMER,
-
- /** Message transmission event. */
- PJSIP_EVENT_TX_MSG,
-
- /** Message received event. */
- PJSIP_EVENT_RX_MSG,
-
- /** Transport error event. */
- PJSIP_EVENT_TRANSPORT_ERROR,
-
- /** Transaction state changed event. */
- PJSIP_EVENT_TSX_STATE,
-
- /** 2xx response received event. */
- PJSIP_EVENT_RX_200_MSG,
-
- /** ACK request received event. */
- PJSIP_EVENT_RX_ACK_MSG,
-
- /** Message discarded event. */
- PJSIP_EVENT_DISCARD_MSG,
-
- /** Indicates that the event was triggered by user action. */
- PJSIP_EVENT_USER,
-
- /** On before transmitting message. */
- PJSIP_EVENT_PRE_TX_MSG,
-
-} pjsip_event_id_e;
-
-
-/**
- * \struct
- * \brief Event descriptor to fully identify a SIP event.
- *
- * Events are the only way for a lower layer object to inform something
- * to higher layer objects. Normally this is achieved by means of callback,
- * i.e. the higher layer objects register a callback to handle the event on
- * the lower layer objects.
- *
- * This event descriptor is used for example by transactions, to inform
- * endpoint about events, and by transports, to inform endpoint about
- * unexpected transport error.
- */
-struct pjsip_event
-{
- /** This is necessary so that we can put events as a list. */
- PJ_DECL_LIST_MEMBER(struct pjsip_event);
-
- /** The event type, can be any value of \b pjsip_event_id_e.
- */
- pjsip_event_id_e type;
-
- /*
- * The event body.
- * By convention, the first member of each struct in the union must be
- * the pointer which is relevant to the event.
- */
- union
- {
- /** Timer event. */
- struct
- {
- pj_timer_entry *entry; /**< The timer entry. */
- } timer;
-
- /** Transaction state has changed event. */
- struct
- {
- union
- {
- pjsip_rx_data *rdata; /**< The incoming message. */
- pjsip_tx_data *tdata; /**< The outgoing message. */
- pj_timer_entry *timer; /**< The timer. */
- pj_status_t status;/**< Transport error status. */
- void *data; /**< Generic data. */
- } src;
- pjsip_transaction *tsx; /**< The transaction. */
- pjsip_event_id_e type; /**< Type of event source:
- * - PJSIP_EVENT_TX_MSG
- * - PJSIP_EVENT_RX_MSG,
- * - PJSIP_EVENT_TRANSPORT_ERROR
- * - PJSIP_EVENT_TIMER
- * - PJSIP_EVENT_USER
- */
- } tsx_state;
-
- /** Message transmission event. */
- struct
- {
- pjsip_tx_data *tdata; /**< The transmit data buffer. */
- pjsip_transaction *tsx; /**< The transaction. */
-
- } tx_msg;
-
- /** Pre-transmission event. */
- struct
- {
- pjsip_tx_data *tdata; /**< Msg to be transmitted. */
- pjsip_transaction *tsx; /**< The transaction. */
- int retcnt;/**< Retransmission count. */
- } pre_tx_msg;
-
- /** Transmission error event. */
- struct
- {
- pjsip_tx_data *tdata; /**< The transmit data. */
- pjsip_transaction *tsx; /**< The transaction. */
- } tx_error;
-
- /** Message arrival event. */
- struct
- {
- pjsip_rx_data *rdata; /**< The receive data buffer. */
- pjsip_transaction *tsx; /**< The transaction. */
- } rx_msg;
-
- /** Receipt of 200/INVITE response. */
- struct
- {
- pjsip_rx_data *rdata; /**< The 200 response msg. */
- } rx_200_msg;
-
- /** Receipt of ACK message. */
- struct
- {
- pjsip_rx_data *rdata; /**< The ack message. */
- } rx_ack_msg;
-
- /** Notification that endpoint has discarded a message. */
- struct
- {
- pjsip_rx_data *rdata; /**< The discarded message. */
- pj_status_t reason;/**< The reason. */
- } discard_msg;
-
- /** User event. */
- struct
- {
- void *user1; /**< User data 1. */
- void *user2; /**< User data 2. */
- void *user3; /**< User data 3. */
- void *user4; /**< User data 4. */
- } user;
-
- } body;
-};
-
-/**
- * Init timer event.
- */
-#define PJSIP_EVENT_INIT_TIMER(event,pentry) \
- do { \
- (event).type = PJSIP_EVENT_TIMER; \
- (event).body.timer.entry = pentry; \
- } while (0)
-
-/**
- * Init tsx state event.
- */
-#define PJSIP_EVENT_INIT_TSX_STATE(event,ptsx,ptype,pdata) \
- do { \
- (event).type = PJSIP_EVENT_TSX_STATE; \
- (event).body.tsx_state.tsx = ptsx; \
- (event).body.tsx_state.type = ptype; \
- (event).body.tsx_state.src.data = pdata; \
- } while (0)
-
-/**
- * Init tx msg event.
- */
-#define PJSIP_EVENT_INIT_TX_MSG(event,ptsx,ptdata) \
- do { \
- (event).type = PJSIP_EVENT_TX_MSG; \
- (event).body.tx_msg.tsx = ptsx; \
- (event).body.tx_msg.tdata = ptdata; \
- } while (0)
-
-/**
- * Init rx msg event.
- */
-#define PJSIP_EVENT_INIT_RX_MSG(event,ptsx,prdata) \
- do { \
- (event).type = PJSIP_EVENT_RX_MSG; \
- (event).body.rx_msg.tsx = ptsx; \
- (event).body.rx_msg.rdata = prdata; \
- } while (0)
-
-/**
- * Init transport error event.
- */
-#define PJSIP_EVENT_INIT_TRANSPORT_ERROR(event,ptsx,ptdata) \
- do { \
- (event).type = PJSIP_EVENT_TRANSPORT_ERROR; \
- (event).body.tx_error.tsx = ptsx; \
- (event).body.tx_error.tdata = ptdata; \
- } while (0)
-
-/**
- * Init rx 200/INVITE event.
- */
-#define PJSIP_EVENT_INIT_RX_200_MSG(event,prdata) \
- do { \
- (event).type = PJSIP_EVENT_RX_200_MSG; \
- (event).body.rx_200_msg.rdata = prdata; \
- } while (0)
-
-/**
- * Init rx ack msg event.
- */
-#define PJSIP_EVENT_INIT_RX_ACK_MSG(event,prdata) \
- do { \
- (event).type = PJSIP_EVENT_RX_ACK_MSG; \
- (event).body.rx_ack_msg.rdata = prdata; \
- } while (0)
-
-/**
- * Init discard msg event.
- */
-#define PJSIP_EVENT_INIT_DISCARD_MSG(event,prdata,preason) \
- do { \
- (event).type = PJSIP_EVENT_DISCARD_MSG; \
- (event).body.discard_msg.rdata = prdata; \
- (event).body.discard_msg.reason = preason; \
- } while (0)
-
-/**
- * Init user event.
- */
-#define PJSIP_EVENT_INIT_USER(event,u1,u2,u3,u4) \
- do { \
- (event).type = PJSIP_EVENT_USER; \
- (event).body.user.user1 = (void*)u1; \
- (event).body.user.user2 = (void*)u2; \
- (event).body.user.user3 = (void*)u3; \
- (event).body.user.user4 = (void*)u4; \
- } while (0)
-
-/**
- * Init pre tx msg event.
- */
-#define PJSIP_EVENT_INIT_PRE_TX_MSG(event,ptsx,ptdata,pretcnt) \
- do { \
- (event).type = PJSIP_EVENT_PRE_TX_MSG; \
- (event).body.pre_tx_msg.tsx = ptsx; \
- (event).body.pre_tx_msg.tdata = ptdata; \
- (event).body.pre_tx_msg.retcnt = pretcnt; \
- } while (0)
-
-
-/**
- * Get the event string from the event ID.
- * @param e the event ID.
- * @notes defined in sip_util.c
- */
-PJ_DEF(const char *) pjsip_event_str(pjsip_event_id_e e);
-
-/**
- * @}
- */
-
-PJ_END_DECL
-
-#endif /* __PJSIP_SIP_EVENT_H__ */
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIP_EVENT_H__ +#define __PJSIP_SIP_EVENT_H__ + +/** + * @file sip_event.h + * @brief SIP Event + */ + +PJ_BEGIN_DECL + +/** + * @defgroup PJSIP_EVENT SIP Event + * @ingroup PJSIP + * @{ + */ +#include <pj/types.h> + + +/** + * Event IDs. + */ +typedef enum pjsip_event_id_e +{ + /** Unidentified event. */ + PJSIP_EVENT_UNKNOWN, + + /** Timer event, normally only used internally in transaction. */ + PJSIP_EVENT_TIMER, + + /** Message transmission event. */ + PJSIP_EVENT_TX_MSG, + + /** Message received event. */ + PJSIP_EVENT_RX_MSG, + + /** Transport error event. */ + PJSIP_EVENT_TRANSPORT_ERROR, + + /** Transaction state changed event. */ + PJSIP_EVENT_TSX_STATE, + + /** 2xx response received event. */ + PJSIP_EVENT_RX_200_MSG, + + /** ACK request received event. */ + PJSIP_EVENT_RX_ACK_MSG, + + /** Message discarded event. */ + PJSIP_EVENT_DISCARD_MSG, + + /** Indicates that the event was triggered by user action. */ + PJSIP_EVENT_USER, + + /** On before transmitting message. */ + PJSIP_EVENT_PRE_TX_MSG, + +} pjsip_event_id_e; + + +/** + * \struct + * \brief Event descriptor to fully identify a SIP event. + * + * Events are the only way for a lower layer object to inform something + * to higher layer objects. Normally this is achieved by means of callback, + * i.e. the higher layer objects register a callback to handle the event on + * the lower layer objects. + * + * This event descriptor is used for example by transactions, to inform + * endpoint about events, and by transports, to inform endpoint about + * unexpected transport error. + */ +struct pjsip_event +{ + /** This is necessary so that we can put events as a list. */ + PJ_DECL_LIST_MEMBER(struct pjsip_event); + + /** The event type, can be any value of \b pjsip_event_id_e. + */ + pjsip_event_id_e type; + + /* + * The event body. + * By convention, the first member of each struct in the union must be + * the pointer which is relevant to the event. + */ + union + { + /** Timer event. */ + struct + { + pj_timer_entry *entry; /**< The timer entry. */ + } timer; + + /** Transaction state has changed event. */ + struct + { + union + { + pjsip_rx_data *rdata; /**< The incoming message. */ + pjsip_tx_data *tdata; /**< The outgoing message. */ + pj_timer_entry *timer; /**< The timer. */ + pj_status_t status;/**< Transport error status. */ + void *data; /**< Generic data. */ + } src; + pjsip_transaction *tsx; /**< The transaction. */ + pjsip_event_id_e type; /**< Type of event source: + * - PJSIP_EVENT_TX_MSG + * - PJSIP_EVENT_RX_MSG, + * - PJSIP_EVENT_TRANSPORT_ERROR + * - PJSIP_EVENT_TIMER + * - PJSIP_EVENT_USER + */ + } tsx_state; + + /** Message transmission event. */ + struct + { + pjsip_tx_data *tdata; /**< The transmit data buffer. */ + pjsip_transaction *tsx; /**< The transaction. */ + + } tx_msg; + + /** Pre-transmission event. */ + struct + { + pjsip_tx_data *tdata; /**< Msg to be transmitted. */ + pjsip_transaction *tsx; /**< The transaction. */ + int retcnt;/**< Retransmission count. */ + } pre_tx_msg; + + /** Transmission error event. */ + struct + { + pjsip_tx_data *tdata; /**< The transmit data. */ + pjsip_transaction *tsx; /**< The transaction. */ + } tx_error; + + /** Message arrival event. */ + struct + { + pjsip_rx_data *rdata; /**< The receive data buffer. */ + pjsip_transaction *tsx; /**< The transaction. */ + } rx_msg; + + /** Receipt of 200/INVITE response. */ + struct + { + pjsip_rx_data *rdata; /**< The 200 response msg. */ + } rx_200_msg; + + /** Receipt of ACK message. */ + struct + { + pjsip_rx_data *rdata; /**< The ack message. */ + } rx_ack_msg; + + /** Notification that endpoint has discarded a message. */ + struct + { + pjsip_rx_data *rdata; /**< The discarded message. */ + pj_status_t reason;/**< The reason. */ + } discard_msg; + + /** User event. */ + struct + { + void *user1; /**< User data 1. */ + void *user2; /**< User data 2. */ + void *user3; /**< User data 3. */ + void *user4; /**< User data 4. */ + } user; + + } body; +}; + +/** + * Init timer event. + */ +#define PJSIP_EVENT_INIT_TIMER(event,pentry) \ + do { \ + (event).type = PJSIP_EVENT_TIMER; \ + (event).body.timer.entry = pentry; \ + } while (0) + +/** + * Init tsx state event. + */ +#define PJSIP_EVENT_INIT_TSX_STATE(event,ptsx,ptype,pdata) \ + do { \ + (event).type = PJSIP_EVENT_TSX_STATE; \ + (event).body.tsx_state.tsx = ptsx; \ + (event).body.tsx_state.type = ptype; \ + (event).body.tsx_state.src.data = pdata; \ + } while (0) + +/** + * Init tx msg event. + */ +#define PJSIP_EVENT_INIT_TX_MSG(event,ptsx,ptdata) \ + do { \ + (event).type = PJSIP_EVENT_TX_MSG; \ + (event).body.tx_msg.tsx = ptsx; \ + (event).body.tx_msg.tdata = ptdata; \ + } while (0) + +/** + * Init rx msg event. + */ +#define PJSIP_EVENT_INIT_RX_MSG(event,ptsx,prdata) \ + do { \ + (event).type = PJSIP_EVENT_RX_MSG; \ + (event).body.rx_msg.tsx = ptsx; \ + (event).body.rx_msg.rdata = prdata; \ + } while (0) + +/** + * Init transport error event. + */ +#define PJSIP_EVENT_INIT_TRANSPORT_ERROR(event,ptsx,ptdata) \ + do { \ + (event).type = PJSIP_EVENT_TRANSPORT_ERROR; \ + (event).body.tx_error.tsx = ptsx; \ + (event).body.tx_error.tdata = ptdata; \ + } while (0) + +/** + * Init rx 200/INVITE event. + */ +#define PJSIP_EVENT_INIT_RX_200_MSG(event,prdata) \ + do { \ + (event).type = PJSIP_EVENT_RX_200_MSG; \ + (event).body.rx_200_msg.rdata = prdata; \ + } while (0) + +/** + * Init rx ack msg event. + */ +#define PJSIP_EVENT_INIT_RX_ACK_MSG(event,prdata) \ + do { \ + (event).type = PJSIP_EVENT_RX_ACK_MSG; \ + (event).body.rx_ack_msg.rdata = prdata; \ + } while (0) + +/** + * Init discard msg event. + */ +#define PJSIP_EVENT_INIT_DISCARD_MSG(event,prdata,preason) \ + do { \ + (event).type = PJSIP_EVENT_DISCARD_MSG; \ + (event).body.discard_msg.rdata = prdata; \ + (event).body.discard_msg.reason = preason; \ + } while (0) + +/** + * Init user event. + */ +#define PJSIP_EVENT_INIT_USER(event,u1,u2,u3,u4) \ + do { \ + (event).type = PJSIP_EVENT_USER; \ + (event).body.user.user1 = (void*)u1; \ + (event).body.user.user2 = (void*)u2; \ + (event).body.user.user3 = (void*)u3; \ + (event).body.user.user4 = (void*)u4; \ + } while (0) + +/** + * Init pre tx msg event. + */ +#define PJSIP_EVENT_INIT_PRE_TX_MSG(event,ptsx,ptdata,pretcnt) \ + do { \ + (event).type = PJSIP_EVENT_PRE_TX_MSG; \ + (event).body.pre_tx_msg.tsx = ptsx; \ + (event).body.pre_tx_msg.tdata = ptdata; \ + (event).body.pre_tx_msg.retcnt = pretcnt; \ + } while (0) + + +/** + * Get the event string from the event ID. + * @param e the event ID. + * @notes defined in sip_util.c + */ +PJ_DEF(const char *) pjsip_event_str(pjsip_event_id_e e); + +/** + * @} + */ + +PJ_END_DECL + +#endif /* __PJSIP_SIP_EVENT_H__ */ diff --git a/pjsip/include/pjsip/sip_module.h b/pjsip/include/pjsip/sip_module.h index bd3bcd87..345be88a 100644 --- a/pjsip/include/pjsip/sip_module.h +++ b/pjsip/include/pjsip/sip_module.h @@ -1,140 +1,140 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIP_MODULE_H__
-#define __PJSIP_SIP_MODULE_H__
-
-/**
- * @file sip_module.h
- * @brief Module helpers
- */
-#include <pjsip/sip_types.h>
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJSIP_MOD SIP Modules
- * @ingroup PJSIP
- * @{
- */
-
-/**
- * Module registration structure, which is passed by the module to the
- * endpoint during the module registration process. This structure enables
- * the endpoint to query the module capability and to further communicate
- * with the module.
- */
-struct pjsip_module
-{
- /**
- * Module name.
- */
- pj_str_t name;
-
- /**
- * Flag to indicate the type of interfaces supported by the module.
- */
- pj_uint32_t flag;
-
- /**
- * Integer number to identify module initialization and start order with
- * regard to other modules. Higher number will make the module gets
- * initialized later.
- */
- pj_uint32_t priority;
-
- /**
- * Opaque data which can be used by a module to identify a resource within
- * the module itself.
- */
- void *mod_data;
-
- /**
- * Number of methods supported by this module.
- */
- int method_cnt;
-
- /**
- * Array of methods supported by this module.
- */
- const pjsip_method *methods[8];
-
- /**
- * Pointer to function to be called to initialize the module.
- *
- * @param endpt The endpoint instance.
- * @param mod The module.
- * @param id The unique module ID assigned to this module.
- *
- * @return Module should return zero when initialization succeed.
- */
- pj_status_t (*init_module)(pjsip_endpoint *endpt,
- struct pjsip_module *mod, pj_uint32_t id);
-
- /**
- * Pointer to function to be called to start the module.
- *
- * @param mod The module.
- *
- * @return Module should return zero to indicate success.
- */
- pj_status_t (*start_module)(struct pjsip_module *mod);
-
- /**
- * Pointer to function to be called to deinitialize the module before
- * it is unloaded.
- *
- * @param mod The module.
- *
- * @return Module should return zero to indicate success.
- */
- pj_status_t (*deinit_module)(struct pjsip_module *mod);
-
- /**
- * Pointer to function to receive transaction related events.
- * If the module doesn't wish to receive such notification, this member
- * must be set to NULL.
- *
- * @param mod The module.
- * @param event The transaction event.
- */
- void (*tsx_handler)(struct pjsip_module *mod, pjsip_event *event);
-};
-
-
-/**
- * Prototype of function to register static modules (eg modules that are
- * linked staticly with the application). This function must be implemented
- * by any applications that use PJSIP library.
- *
- * @param count [input/output] On input, it contains the maximum number of
- * elements in the array. On output, the function fills with
- * the number of modules to be registered.
- * @param modules [output] array of pointer to modules to be registered.
- */
-pj_status_t register_static_modules( pj_size_t *count,
- pjsip_module **modules );
-
-/**
- * @}
- */
-
-PJ_END_DECL
-
-#endif /* __PJSIP_SIP_MODULE_H__ */
-
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIP_MODULE_H__ +#define __PJSIP_SIP_MODULE_H__ + +/** + * @file sip_module.h + * @brief Module helpers + */ +#include <pjsip/sip_types.h> + +PJ_BEGIN_DECL + +/** + * @defgroup PJSIP_MOD SIP Modules + * @ingroup PJSIP + * @{ + */ + +/** + * Module registration structure, which is passed by the module to the + * endpoint during the module registration process. This structure enables + * the endpoint to query the module capability and to further communicate + * with the module. + */ +struct pjsip_module +{ + /** + * Module name. + */ + pj_str_t name; + + /** + * Flag to indicate the type of interfaces supported by the module. + */ + pj_uint32_t flag; + + /** + * Integer number to identify module initialization and start order with + * regard to other modules. Higher number will make the module gets + * initialized later. + */ + pj_uint32_t priority; + + /** + * Opaque data which can be used by a module to identify a resource within + * the module itself. + */ + void *mod_data; + + /** + * Number of methods supported by this module. + */ + int method_cnt; + + /** + * Array of methods supported by this module. + */ + const pjsip_method *methods[8]; + + /** + * Pointer to function to be called to initialize the module. + * + * @param endpt The endpoint instance. + * @param mod The module. + * @param id The unique module ID assigned to this module. + * + * @return Module should return zero when initialization succeed. + */ + pj_status_t (*init_module)(pjsip_endpoint *endpt, + struct pjsip_module *mod, pj_uint32_t id); + + /** + * Pointer to function to be called to start the module. + * + * @param mod The module. + * + * @return Module should return zero to indicate success. + */ + pj_status_t (*start_module)(struct pjsip_module *mod); + + /** + * Pointer to function to be called to deinitialize the module before + * it is unloaded. + * + * @param mod The module. + * + * @return Module should return zero to indicate success. + */ + pj_status_t (*deinit_module)(struct pjsip_module *mod); + + /** + * Pointer to function to receive transaction related events. + * If the module doesn't wish to receive such notification, this member + * must be set to NULL. + * + * @param mod The module. + * @param event The transaction event. + */ + void (*tsx_handler)(struct pjsip_module *mod, pjsip_event *event); +}; + + +/** + * Prototype of function to register static modules (eg modules that are + * linked staticly with the application). This function must be implemented + * by any applications that use PJSIP library. + * + * @param count [input/output] On input, it contains the maximum number of + * elements in the array. On output, the function fills with + * the number of modules to be registered. + * @param modules [output] array of pointer to modules to be registered. + */ +pj_status_t register_static_modules( pj_size_t *count, + pjsip_module **modules ); + +/** + * @} + */ + +PJ_END_DECL + +#endif /* __PJSIP_SIP_MODULE_H__ */ + diff --git a/pjsip/include/pjsip/sip_msg.h b/pjsip/include/pjsip/sip_msg.h index a547bfa2..836ce37b 100644 --- a/pjsip/include/pjsip/sip_msg.h +++ b/pjsip/include/pjsip/sip_msg.h @@ -1,1527 +1,1527 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIP_MSG_H__
-#define __PJSIP_SIP_MSG_H__
-
-/**
- * @file sip_msg.h
- * @brief SIP Message Structure.
- */
-
-#include <pjsip/sip_types.h>
-#include <pjsip/sip_uri.h>
-#include <pj/list.h>
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJSIP_MSG SIP Message Structure
- * @ingroup PJSIP
- * @{
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_METHOD Methods
- * @brief Method names and manipulation.
- * @ingroup PJSIP_MSG
- * @{
- */
-
-/**
- * This enumeration declares SIP methods as described by RFC3261. Additional
- * methods do exist, and they are described by corresponding RFCs for the SIP
- * extentensions. Since they won't alter the characteristic of the processing
- * of the message, they don't need to be explicitly mentioned here.
- */
-typedef enum pjsip_method_e
-{
- /** INVITE method, for establishing dialogs. */
- PJSIP_INVITE_METHOD,
-
- /** CANCEL method, for cancelling request. */
- PJSIP_CANCEL_METHOD,
-
- /** ACK method, for acknowledging final response to INVITE. */
- PJSIP_ACK_METHOD,
-
- /** BYE method, for terminating dialog. */
- PJSIP_BYE_METHOD,
-
- /** REGISTER method. */
- PJSIP_REGISTER_METHOD,
-
- /** OPTIONS method, for querying remote capabilities. */
- PJSIP_OPTIONS_METHOD,
-
- /** Other method, which means that the method name itself will be stored
- elsewhere. */
- PJSIP_OTHER_METHOD,
-
-} pjsip_method_e;
-
-
-
-/**
- * This structure represents a SIP method.
- * Application must always use either #pjsip_method_init or #pjsip_method_set
- * to make sure that method name is initialized correctly. This way, the name
- * member will always contain a valid method string regardless whether the ID
- * is recognized or not.
- */
-typedef struct pjsip_method
-{
- pjsip_method_e id; /**< Method ID, from \a pjsip_method_e. */
- pj_str_t name; /**< Method name, which will always contain the
- method string. */
-} pjsip_method;
-
-
-/**
- * Initialize the method structure from a string.
- * This function will check whether the method is a known method then set
- * both the id and name accordingly.
- *
- * @param m The method to initialize.
- * @param pool Pool where memory allocation will be allocated from, if required.
- * @param str The method string.
- */
-PJ_DECL(void) pjsip_method_init( pjsip_method *m,
- pj_pool_t *pool,
- const pj_str_t *str);
-
-/**
- * Initialize the method structure from a string, without cloning the string.
- * See #pjsip_method_init.
- *
- * @param m The method structure to be initialized.
- * @param str The method string.
- */
-PJ_DECL(void) pjsip_method_init_np( pjsip_method *m,
- pj_str_t *str);
-
-/**
- * Set the method with the predefined method ID.
- * This function will also set the name member of the structure to the correct
- * string according to the method.
- *
- * @param m The method structure.
- * @param id The method ID.
- */
-PJ_DECL(void) pjsip_method_set( pjsip_method *m, pjsip_method_e id );
-
-
-/**
- * Copy one method structure to another. If the method is of the known methods,
- * then memory allocation is not required.
- *
- * @param pool Pool to allocate memory from, if required.
- * @param method The destination method to copy to.
- * @param rhs The source method to copy from.
- */
-PJ_DECL(void) pjsip_method_copy( pj_pool_t *pool,
- pjsip_method *method,
- const pjsip_method *rhs );
-
-/**
- * Compare one method with another, and conveniently determine whether the
- * first method is equal, less than, or greater than the second method.
- *
- * @param m1 The first method.
- * @param m2 The second method.
- *
- * @return Zero if equal, otherwise will return -1 if less or +1 if greater.
- */
-PJ_DECL(int) pjsip_method_cmp( const pjsip_method *m1, const pjsip_method *m2);
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR Header Fields General Structure.
- * @brief General Header Fields Structure.
- * @ingroup PJSIP_MSG
- * @{
- */
-
-/**
- * Header types, as defined by RFC3261.
- */
-typedef enum pjsip_hdr_e
-{
- /*
- * These are the headers documented in RFC3261. Headers not documented
- * there must have type PJSIP_H_OTHER, and the header type itself is
- * recorded in the header name string.
- *
- * DO NOT CHANGE THE VALUE/ORDER OF THE HEADER IDs!!!.
- */
- PJSIP_H_ACCEPT,
- PJSIP_H_ACCEPT_ENCODING_UNIMP,
- PJSIP_H_ACCEPT_LANGUAGE_UNIMP,
- PJSIP_H_ALERT_INFO_UNIMP,
- PJSIP_H_ALLOW,
- PJSIP_H_AUTHENTICATION_INFO_UNIMP,
- PJSIP_H_AUTHORIZATION,
- PJSIP_H_CALL_ID,
- PJSIP_H_CALL_INFO_UNIMP,
- PJSIP_H_CONTACT,
- PJSIP_H_CONTENT_DISPOSITION_UNIMP,
- PJSIP_H_CONTENT_ENCODING_UNIMP,
- PJSIP_H_CONTENT_LANGUAGE_UNIMP,
- PJSIP_H_CONTENT_LENGTH,
- PJSIP_H_CONTENT_TYPE,
- PJSIP_H_CSEQ,
- PJSIP_H_DATE_UNIMP,
- PJSIP_H_ERROR_INFO_UNIMP,
- PJSIP_H_EXPIRES,
- PJSIP_H_FROM,
- PJSIP_H_IN_REPLY_TO_UNIMP,
- PJSIP_H_MAX_FORWARDS,
- PJSIP_H_MIME_VERSION_UNIMP,
- PJSIP_H_MIN_EXPIRES,
- PJSIP_H_ORGANIZATION_UNIMP,
- PJSIP_H_PRIORITY_UNIMP,
- PJSIP_H_PROXY_AUTHENTICATE,
- PJSIP_H_PROXY_AUTHORIZATION,
- PJSIP_H_PROXY_REQUIRE_UNIMP,
- PJSIP_H_RECORD_ROUTE,
- PJSIP_H_REPLY_TO_UNIMP,
- PJSIP_H_REQUIRE,
- PJSIP_H_RETRY_AFTER,
- PJSIP_H_ROUTE,
- PJSIP_H_SERVER_UNIMP,
- PJSIP_H_SUBJECT_UNIMP,
- PJSIP_H_SUPPORTED,
- PJSIP_H_TIMESTAMP_UNIMP,
- PJSIP_H_TO,
- PJSIP_H_UNSUPPORTED,
- PJSIP_H_USER_AGENT_UNIMP,
- PJSIP_H_VIA,
- PJSIP_H_WARNING_UNIMP,
- PJSIP_H_WWW_AUTHENTICATE,
-
- PJSIP_H_OTHER,
-
-} pjsip_hdr_e;
-
-/**
- * This structure provides the pointer to basic functions that are needed
- * for generic header operations. All header fields will have pointer to
- * this structure, so that they can be manipulated uniformly.
- */
-typedef struct pjsip_hdr_vptr
-{
- /**
- * Function to clone the header.
- *
- * @param pool Memory pool to allocate the new header.
- * @param hdr Header to clone.
- *
- * @return A new instance of the header.
- */
- void *(*clone)(pj_pool_t *pool, const void *hdr);
-
- /**
- * Pointer to function to shallow clone the header.
- * Shallow cloning will just make a memory copy of the original header,
- * thus all pointers in original header will be kept intact. Because the
- * function does not need to perform deep copy, the operation should be
- * faster, but the application must make sure that the original header
- * is still valid throughout the lifetime of new header.
- *
- * @param pool Memory pool to allocate the new header.
- * @param hdr The header to clone.
- */
- void *(*shallow_clone)(pj_pool_t *pool, const void *hdr);
-
- /** Pointer to function to print the header to the specified buffer.
- * Returns the length of string written, or -1 if the remaining buffer
- * is not enough to hold the header.
- *
- * @param hdr The header to print.
- * @param buf The buffer.
- * @param len The size of the buffer.
- *
- * @return The size copied to buffer, or -1 if there's not enough space.
- */
- int (*print_on)(void *hdr, char *buf, pj_size_t len);
-
-} pjsip_hdr_vptr;
-
-
-/**
- * Generic fields for all SIP headers are declared using this macro, to make
- * sure that all headers will have exactly the same layout in their start of
- * the storage. This behaves like C++ inheritance actually.
- */
-#define PJSIP_DECL_HDR_MEMBER(hdr) \
- /** List members. */ \
- PJ_DECL_LIST_MEMBER(hdr); \
- /** Header type */ \
- pjsip_hdr_e type; \
- /** Header name. */ \
- pj_str_t name; \
- /** Header short name version. */ \
- pj_str_t sname; \
- /** Virtual function table. */ \
- pjsip_hdr_vptr *vptr
-
-
-/**
- * Generic SIP header structure, for generic manipulation for headers in the
- * message. All header fields can be typecasted to this type.
- */
-struct pjsip_hdr
-{
- PJSIP_DECL_HDR_MEMBER(struct pjsip_hdr);
-};
-
-
-/**
- * This generic function will clone any header, by calling "clone" function
- * in header's virtual function table.
- *
- * @param pool The pool to allocate memory from.
- * @param hdr The header to clone.
- *
- * @return A new instance copied from the original header.
- */
-PJ_DECL(void*) pjsip_hdr_clone( pj_pool_t *pool, const void *hdr );
-
-
-/**
- * This generic function will clone any header, by calling "shallow_clone"
- * function in header's virtual function table.
- *
- * @param pool The pool to allocate memory from.
- * @param hdr The header to clone.
- *
- * @return A new instance copied from the original header.
- */
-PJ_DECL(void*) pjsip_hdr_shallow_clone( pj_pool_t *pool, const void *hdr );
-
-/**
- * This generic function will print any header, by calling "print"
- * function in header's virtual function table.
- *
- * @param hdr The header to print.
- * @param buf The buffer.
- * @param len The size of the buffer.
- *
- * @return The size copied to buffer, or -1 if there's not enough space.
- */
-PJ_DECL(int) pjsip_hdr_print_on( void *hdr, char *buf, pj_size_t len);
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_LINE Request and Status Line.
- * @brief Request and status line structures and manipulation.
- * @ingroup PJSIP_MSG
- * @{
- */
-
-/**
- * This structure describes SIP request line.
- */
-typedef struct pjsip_request_line
-{
- pjsip_method method; /**< Method for this request line. */
- pjsip_uri *uri; /**< URI for this request line. */
-} pjsip_request_line;
-
-
-/**
- * This structure describes SIP status line.
- */
-typedef struct pjsip_status_line
-{
- int code; /**< Status code. */
- pj_str_t reason; /**< Reason string. */
-} pjsip_status_line;
-
-
-/**
- * This enumeration lists standard SIP status codes according to RFC 3261.
- * In addition, it also declares new status class 7xx for errors generated
- * by the stack. This status class however should not get transmitted on the
- * wire.
- */
-typedef enum pjsip_status_code
-{
- PJSIP_SC_TRYING = 100,
- PJSIP_SC_RINGING = 180,
- PJSIP_SC_CALL_BEING_FORWARDED = 181,
- PJSIP_SC_QUEUED = 182,
- PJSIP_SC_PROGRESS = 183,
-
- PJSIP_SC_OK = 200,
-
- PJSIP_SC_MULTIPLE_CHOICES = 300,
- PJSIP_SC_MOVED_PERMANENTLY = 301,
- PJSIP_SC_MOVED_TEMPORARILY = 302,
- PJSIP_SC_USE_PROXY = 305,
- PJSIP_SC_ALTERNATIVE_SERVICE = 380,
-
- PJSIP_SC_BAD_REQUEST = 400,
- PJSIP_SC_UNAUTHORIZED = 401,
- PJSIP_SC_PAYMENT_REQUIRED = 402,
- PJSIP_SC_FORBIDDEN = 403,
- PJSIP_SC_NOT_FOUND = 404,
- PJSIP_SC_METHOD_NOT_ALLOWED = 405,
- PJSIP_SC_NOT_ACCEPTABLE = 406,
- PJSIP_SC_PROXY_AUTHENTICATION_REQUIRED = 407,
- PJSIP_SC_REQUEST_TIMEOUT = 408,
- PJSIP_SC_GONE = 410,
- PJSIP_SC_REQUEST_ENTITY_TOO_LARGE = 413,
- PJSIP_SC_REQUEST_URI_TOO_LONG = 414,
- PJSIP_SC_UNSUPPORTED_MEDIA_TYPE = 415,
- PJSIP_SC_UNSUPPORTED_URI_SCHEME = 416,
- PJSIP_SC_BAD_EXTENSION = 420,
- PJSIP_SC_EXTENSION_REQUIRED = 421,
- PJSIP_SC_INTERVAL_TOO_BRIEF = 423,
- PJSIP_SC_TEMPORARILY_UNAVAILABLE = 480,
- PJSIP_SC_CALL_TSX_DOES_NOT_EXIST = 481,
- PJSIP_SC_LOOP_DETECTED = 482,
- PJSIP_SC_TOO_MANY_HOPS = 483,
- PJSIP_SC_ADDRESS_INCOMPLETE = 484,
- PJSIP_AC_AMBIGUOUS = 485,
- PJSIP_SC_BUSY_HERE = 486,
- PJSIP_SC_REQUEST_TERMINATED = 487,
- PJSIP_SC_NOT_ACCEPTABLE_HERE = 488,
- PJSIP_SC_REQUEST_PENDING = 491,
- PJSIP_SC_UNDECIPHERABLE = 493,
-
- PJSIP_SC_INTERNAL_SERVER_ERROR = 500,
- PJSIP_SC_NOT_IMPLEMENTED = 501,
- PJSIP_SC_BAD_GATEWAY = 502,
- PJSIP_SC_SERVICE_UNAVAILABLE = 503,
- PJSIP_SC_SERVER_TIMEOUT = 504,
- PJSIP_SC_VERSION_NOT_SUPPORTED = 505,
- PJSIP_SC_MESSAGE_TOO_LARGE = 513,
-
- PJSIP_SC_BUSY_EVERYWHERE = 600,
- PJSIP_SC_DECLINE = 603,
- PJSIP_SC_DOES_NOT_EXIST_ANYWHERE = 604,
- PJSIP_SC_NOT_ACCEPTABLE_ANYWHERE = 606,
-
- PJSIP_SC_TSX_TIMEOUT = 701,
- PJSIP_SC_TSX_RESOLVE_ERROR = 702,
- PJSIP_SC_TSX_TRANSPORT_ERROR = 703,
-
-} pjsip_status_code;
-
-/**
- * Get the default status text for the status code.
- *
- * @param status_code SIP Status Code
- *
- * @return textual message for the status code.
- */
-PJ_DECL(const pj_str_t*) pjsip_get_status_text(int status_code);
-
-/**
- * This macro returns non-zero (TRUE) if the specified status_code is
- * in the same class as the code_class.
- *
- * @param status_code The status code.
- * @param code_class The status code in the class (for example 100, 200).
- */
-#define PJSIP_IS_STATUS_IN_CLASS(status_code, code_class) \
- (status_code/100 == code_class/100)
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @addtogroup PJSIP_MSG_MEDIA Media Type
- * @brief Media type definitions and manipulations.
- * @ingroup PJSIP_MSG
- * @{
- */
-
-/**
- * This structure describes SIP media type, as used for example in
- * Accept and Content-Type header..
- */
-typedef struct pjsip_media_type
-{
- pj_str_t type; /**< Media type. */
- pj_str_t subtype; /**< Media subtype. */
- pj_str_t param; /**< Media type parameters (concatenated). */
-} pjsip_media_type;
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @addtogroup PJSIP_MSG_BODY Message Body
- * @brief SIP message body structures and manipulation.
- * @ingroup PJSIP_MSG
- * @{
- */
-
-/**
- * Generic abstraction to message body.
- * When an incoming message is parsed (pjsip_parse_msg()), the parser fills in
- * all members with the appropriate value. The 'data' and 'len' member will
- * describe portion of incoming packet which denotes the message body.
- * When application needs to attach message body to outgoing SIP message, it
- * must fill in all members of this structure.
- */
-typedef struct pjsip_msg_body
-{
- /** MIME content type.
- * For incoming messages, the parser will fill in this member with the
- * content type found in Content-Type header.
- *
- * For outgoing messages, application must fill in this member with
- * appropriate value, because the stack will generate Content-Type header
- * based on the value specified here.
- */
- pjsip_media_type content_type;
-
- /** Pointer to buffer which holds the message body data.
- * For incoming messages, the parser will fill in this member with the
- * pointer to the body string.
- *
- * When sending outgoing message, this member doesn't need to point to the
- * actual message body string. It can be assigned with arbitrary pointer,
- * because the value will only need to be understood by the print_body()
- * function. The stack itself will not try to interpret this value, but
- * instead will always call the print_body() whenever it needs to get the
- * actual body string.
- */
- void *data;
-
- /** The length of the data.
- * For incoming messages, the parser will fill in this member with the
- * actual length of message body.
- *
- * When sending outgoing message, again just like the "data" member, the
- * "len" member doesn't need to point to the actual length of the body
- * string.
- */
- unsigned len;
-
- /** Pointer to function to print this message body.
- * Application must set a proper function here when sending outgoing
- * message.
- *
- * @param msg_body This structure itself.
- * @param buf The buffer.
- * @param size The buffer size.
- *
- * @return The length of the string printed, or -1 if there is
- * not enough space in the buffer to print the whole
- * message body.
- */
- int (*print_body)(struct pjsip_msg_body *msg_body,
- char *buf, pj_size_t size);
-
-} pjsip_msg_body;
-
-/**
- * General purpose function to textual data in a SIP body. Attach this function
- * in a SIP message body only if the data in pjsip_msg_body is a textual
- * message ready to be embedded in a SIP message. If the data in the message
- * body is not a textual body, then application must supply a custom function
- * to print that body.
- *
- * @param msg_body The message body.
- * @param buf Buffer to copy the message body to.
- * @param size The size of the buffer.
- *
- * @return The length copied to the buffer, or -1.
- */
-PJ_DECL(int) pjsip_print_text_body( pjsip_msg_body *msg_body,
- char *buf, pj_size_t size);
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_MSG Message Structure
- * @brief Message structure and operations.
- * @ingroup PJSIP_MSG
- * @{
- */
-
-/**
- * Message type (request or response).
- */
-typedef enum pjsip_msg_type_e
-{
- PJSIP_REQUEST_MSG, /**< Indicates request message. */
- PJSIP_RESPONSE_MSG, /**< Indicates response message. */
-} pjsip_msg_type_e;
-
-
-/**
- * This structure describes a SIP message.
- */
-struct pjsip_msg
-{
- /** Message type (ie request or response). */
- pjsip_msg_type_e type;
-
- /** The first line of the message can be either request line for request
- * messages, or status line for response messages. It is represented here
- * as a union.
- */
- union
- {
- /** Request Line. */
- struct pjsip_request_line req;
-
- /** Status Line. */
- struct pjsip_status_line status;
- } line;
-
- /** List of message headers. */
- pjsip_hdr hdr;
-
- /** Pointer to message body, or NULL if no message body is attached to
- * this mesage.
- */
- pjsip_msg_body *body;
-};
-
-
-/**
- * Create new request or response message.
- *
- * @param pool The pool.
- * @param type Message type.
- * @return New message, or THROW exception if failed.
- */
-PJ_DECL(pjsip_msg*) pjsip_msg_create( pj_pool_t *pool, pjsip_msg_type_e type);
-
-/**
- * Find a header in the message by the header type.
- *
- * @param msg The message.
- * @param type The header type to find.
- * @param start The first header field where the search should begin.
- * If NULL is specified, then the search will begin from the
- * first header, otherwise the search will begin at the
- * specified header.
- *
- * @return The header field, or NULL if no header with the specified
- * type is found.
- */
-PJ_DECL(void*) pjsip_msg_find_hdr( pjsip_msg *msg,
- pjsip_hdr_e type, void *start);
-
-/**
- * Find a header in the message by its name.
- *
- * @param msg The message.
- * @param name The header name to find.
- * @param start The first header field where the search should begin.
- * If NULL is specified, then the search will begin from the
- * first header, otherwise the search will begin at the
- * specified header.
- *
- * @return The header field, or NULL if no header with the specified
- * type is found.
- */
-PJ_DECL(void*) pjsip_msg_find_hdr_by_name( pjsip_msg *msg,
- const pj_str_t *name, void *start);
-
-/**
- * Find and remove a header in the message.
- *
- * @param msg The message.
- * @param hdr The header type to find.
- * @param start The first header field where the search should begin,
- * or NULL to search from the first header in the message.
- *
- * @return The header field, or NULL if not found.
- */
-PJ_DECL(void*) pjsip_msg_find_remove_hdr( pjsip_msg *msg,
- pjsip_hdr_e hdr, void *start);
-
-/**
- * Add a header to the message, putting it last in the header list.
- *
- * @param msg The message.
- * @param hdr The header to add.
- *
- * @bug Once the header is put in a list (or message), it can not be put in
- * other list (or message). Otherwise Real Bad Thing will happen.
- */
-PJ_IDECL(void) pjsip_msg_add_hdr( pjsip_msg *msg, pjsip_hdr *hdr );
-
-/**
- * Add header field to the message, putting it in the front of the header list.
- *
- * @param msg The message.
- * @param hdr The header to add.
- *
- * @bug Once the header is put in a list (or message), it can not be put in
- * other list (or message). Otherwise Real Bad Thing will happen.
- */
-PJ_IDECL(void) pjsip_msg_insert_first_hdr( pjsip_msg *msg, pjsip_hdr *hdr );
-
-/**
- * Print the message to the specified buffer.
- *
- * @param msg The message to print.
- * @param buf The buffer
- * @param size The size of the buffer.
- *
- * @return The length of the printed characters (in bytes), or NEGATIVE
- * value if the message is too large for the specified buffer.
- */
-PJ_DECL(pj_ssize_t) pjsip_msg_print(pjsip_msg *msg, char *buf, pj_size_t size);
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @addtogroup PJSIP_MSG_HDR_GEN Header Field: Generic
- * @brief Generic header field which contains header name and value.
- * @ingroup PJSIP_MSG
- * @{
- */
-
-/**
- * Generic SIP header, which contains hname and a string hvalue.
- * Note that this header is not supposed to be used as 'base' class for headers.
- */
-typedef struct pjsip_generic_string_hdr
-{
- PJSIP_DECL_HDR_MEMBER(struct pjsip_generic_string_hdr); /**< Standard header field. */
- pj_str_t hvalue; /**< hvalue */
-} pjsip_generic_string_hdr;
-
-
-/**
- * Create a new instance of generic header. A generic header can have an
- * arbitrary header name.
- *
- * @param pool The pool.
- * @param hname The header name to be assigned to the header, or NULL to
- * assign the header name with some string.
- *
- * @return The header, or THROW exception.
- */
-PJ_DECL(pjsip_generic_string_hdr*) pjsip_generic_string_hdr_create( pj_pool_t *pool,
- const pj_str_t *hname );
-
-/**
- * Create a generic header along with the text content.
- *
- * @param pool The pool.
- * @param hname The header name.
- * @param hvalue The header text content.
- *
- * @return The header instance.
- */
-PJ_DECL(pjsip_generic_string_hdr*)
-pjsip_generic_string_hdr_create_with_text( pj_pool_t *pool,
- const pj_str_t *hname,
- const pj_str_t *hvalue);
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @addtogroup PJSIP_MSG_HDR_GEN_INT Header Field: Generic Integer
- * @brief Generic header field which contains header name and value.
- * @ingroup PJSIP_MSG
- * @{
- */
-
-/**
- * Generic SIP header, which contains hname and a string hvalue.
- */
-typedef struct pjsip_generic_int_hdr
-{
- PJSIP_DECL_HDR_MEMBER(struct pjsip_generic_int_hdr); /**< Standard header field. */
- pj_int32_t ivalue; /**< ivalue */
-} pjsip_generic_int_hdr;
-
-
-/**
- * Create a new instance of generic header. A generic header can have an
- * arbitrary header name.
- *
- * @param pool The pool.
- * @param hname The header name to be assigned to the header, or NULL to
- * assign the header name with some string.
- *
- * @return The header, or THROW exception.
- */
-PJ_DECL(pjsip_generic_int_hdr*) pjsip_generic_int_hdr_create( pj_pool_t *pool,
- const pj_str_t *hname );
-
-/**
- * Create a generic header along with the value.
- *
- * @param pool The pool.
- * @param hname The header name.
- * @param value The header value content.
- *
- * @return The header instance.
- */
-PJ_DECL(pjsip_generic_int_hdr*)
-pjsip_generic_int_hdr_create_with_value( pj_pool_t *pool,
- const pj_str_t *hname,
- int value);
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR_GENERIC_LIST Header Field: Generic string list.
- * @brief Header with list of strings separated with comma
- * @ingroup PJSIP_MSG
- * @{
- */
-
-/** Maximum elements in the header array. */
-#define PJSIP_GENERIC_ARRAY_MAX_COUNT 32
-
-typedef struct pjsip_generic_array_hdr
-{
- PJSIP_DECL_HDR_MEMBER(struct pjsip_generic_array_hdr);
- unsigned count; /**< Number of elements. */
- pj_str_t values[PJSIP_GENERIC_ARRAY_MAX_COUNT]; /**< Elements. */
-} pjsip_generic_array_hdr;
-
-/**
- * Create generic array header.
- *
- * @param pool Pool to allocate memory from.
- *
- * @return New generic array header.
- */
-PJ_DECL(pjsip_generic_array_hdr*) pjsip_generic_array_create(pj_pool_t *pool,
- const pj_str_t *hnames);
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR_ACCEPT Header Field: Accept
- * @brief Accept header field.
- * @ingroup PJSIP_MSG
- * @{
- */
-/** Accept header. */
-typedef pjsip_generic_array_hdr pjsip_accept_hdr;
-
-/** Maximum fields in Accept header. */
-#define PJSIP_MAX_ACCEPT_COUNT PJSIP_GENERIC_ARRAY_MAX_COUNT
-
-/**
- * Create new Accept header instance.
- *
- * @param pool The pool.
- *
- * @return New Accept header instance.
- */
-PJ_DECL(pjsip_accept_hdr*) pjsip_accept_hdr_create(pj_pool_t *pool);
-
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR_ALLOW Header Field: Allow
- * @brief Allow header field.
- * @ingroup PJSIP_MSG
- * @{
- */
-typedef pjsip_generic_array_hdr pjsip_allow_hdr;
-
-/**
- * Create new Allow header instance.
- *
- * @param pool The pool.
- *
- * @return New Allow header instance.
- */
-PJ_DECL(pjsip_allow_hdr*) pjsip_allow_hdr_create(pj_pool_t *pool);
-
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR_CID Header Field: Call-ID
- * @brief Call-ID header field.
- * @ingroup PJSIP_MSG
- * @{
- */
-/**
- * Call-ID header.
- */
-typedef struct pjsip_cid_hdr
-{
- PJSIP_DECL_HDR_MEMBER(struct pjsip_cid_hdr);
- pj_str_t id; /**< Call-ID string. */
-} pjsip_cid_hdr;
-
-
-/**
- * Create new Call-ID header.
- *
- * @param pool The pool.
- *
- * @return new Call-ID header.
- */
-PJ_DECL(pjsip_cid_hdr*) pjsip_cid_hdr_create( pj_pool_t *pool );
-
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR_CLEN Header Field: Content-Length
- * @brief Content-Length header field.
- * @ingroup PJSIP_MSG
- * @{
- */
-/**
- * Content-Length header.
- */
-typedef struct pjsip_clen_hdr
-{
- PJSIP_DECL_HDR_MEMBER(struct pjsip_clen_hdr);
- int len; /**< Content length. */
-} pjsip_clen_hdr;
-
-/**
- * Create new Content-Length header.
- *
- * @param pool the pool.
- * @return A new Content-Length header instance.
- */
-PJ_DECL(pjsip_clen_hdr*) pjsip_clen_hdr_create( pj_pool_t *pool );
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR_CSEQ Header Field: CSeq
- * @brief CSeq header field.
- * @ingroup PJSIP_MSG
- * @{
- */
-/**
- * CSeq header.
- */
-typedef struct pjsip_cseq_hdr
-{
- PJSIP_DECL_HDR_MEMBER(struct pjsip_cseq_hdr);
- int cseq; /**< CSeq number. */
- pjsip_method method; /**< CSeq method. */
-} pjsip_cseq_hdr;
-
-
-/** Create new CSeq header.
- *
- * @param pool The pool.
- * @return A new CSeq header instance.
- */
-PJ_DECL(pjsip_cseq_hdr*) pjsip_cseq_hdr_create( pj_pool_t *pool );
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR_CONTACT Header Field: Contact
- * @brief Contact header field.
- * @ingroup PJSIP_MSG
- * @{
- */
-/**
- * Contact header.
- * In this library, contact header only contains single URI. If a message has
- * multiple URI in the Contact header, the URI will be put in separate Contact
- * headers.
- */
-typedef struct pjsip_contact_hdr
-{
- PJSIP_DECL_HDR_MEMBER(struct pjsip_contact_hdr);
- int star; /**< The contact contains only a '*' character */
- pjsip_uri *uri; /**< URI in the contact. */
- int q1000; /**< The "q" value times 1000 (to avoid float) */
- pj_int32_t expires; /**< Expires parameter, otherwise -1 if not present. */
- pj_str_t other_param; /**< Other parameters, concatenated in a single string. */
-} pjsip_contact_hdr;
-
-
-/**
- * Create a new Contact header.
- *
- * @param pool The pool.
- * @return A new instance of Contact header.
- */
-PJ_DECL(pjsip_contact_hdr*) pjsip_contact_hdr_create( pj_pool_t *pool );
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR_CTYPE Header Field: Content-Type
- * @brief Content-Type header field.
- * @ingroup PJSIP_MSG
- * @{
- */
-/**
- * Content-Type.
- */
-typedef struct pjsip_ctype_hdr
-{
- PJSIP_DECL_HDR_MEMBER(struct pjsip_ctype_hdr);
- pjsip_media_type media; /**< Media type. */
-} pjsip_ctype_hdr;
-
-
-/**
- * Create a nwe Content Type header.
- *
- * @param pool The pool.
- * @return A new Content-Type header.
- */
-PJ_DECL(pjsip_ctype_hdr*) pjsip_ctype_hdr_create( pj_pool_t *pool );
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR_EXPIRES Header Field: Expires
- * @brief Expires header field.
- * @ingroup PJSIP_MSG
- * @{
- */
-/** Expires header. */
-typedef pjsip_generic_int_hdr pjsip_expires_hdr;
-
-/**
- * Create a new Expires header.
- *
- * @param pool The pool.
- * @return A new Expires header.
- */
-PJ_DECL(pjsip_expires_hdr*) pjsip_expires_hdr_create( pj_pool_t *pool );
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR_FROMTO Header Field: From/To
- * @brief From and To header field.
- * @ingroup PJSIP_MSG
- * @{
- */
-/**
- * To or From header.
- */
-typedef struct pjsip_fromto_hdr
-{
- PJSIP_DECL_HDR_MEMBER(struct pjsip_fromto_hdr);
- pjsip_uri *uri; /**< URI in From/To header. */
- pj_str_t tag; /**< Header "tag" parameter. */
- pj_str_t other_param; /**< Other params, concatenated as a single string. */
-} pjsip_fromto_hdr;
-
-/** Alias for From header. */
-typedef pjsip_fromto_hdr pjsip_from_hdr;
-
-/** Alias for To header. */
-typedef pjsip_fromto_hdr pjsip_to_hdr;
-
-/**
- * Create a From header.
- *
- * @param pool The pool.
- * @return New instance of From header.
- */
-PJ_DECL(pjsip_from_hdr*) pjsip_from_hdr_create( pj_pool_t *pool );
-
-/**
- * Create a To header.
- *
- * @param pool The pool.
- * @return New instance of To header.
- */
-PJ_DECL(pjsip_to_hdr*) pjsip_to_hdr_create( pj_pool_t *pool );
-
-/**
- * Convert the header to a From header.
- *
- * @param pool The pool.
- * @return "From" header.
- */
-PJ_DECL(pjsip_from_hdr*) pjsip_fromto_set_from( pjsip_fromto_hdr *hdr );
-
-/**
- * Convert the header to a To header.
- *
- * @param pool The pool.
- * @return "To" header.
- */
-PJ_DECL(pjsip_to_hdr*) pjsip_fromto_set_to( pjsip_fromto_hdr *hdr );
-
-/**
- * @}
- */
-
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR_MAX_FORWARDS Header Field: Max-Forwards
- * @brief Max-Forwards header field.
- * @ingroup PJSIP_MSG
- * @{
- */
-typedef pjsip_generic_int_hdr pjsip_max_forwards_hdr;
-
-/**
- * Create new Max-Forwards header instance.
- *
- * @param pool The pool.
- *
- * @return New Max-Forwards header instance.
- */
-PJ_DECL(pjsip_max_forwards_hdr*) pjsip_max_forwards_hdr_create(pj_pool_t *pool);
-
-
-/**
- * @}
- */
-
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR_MIN_EXPIRES Header Field: Min-Expires
- * @brief Min-Expires header field.
- * @ingroup PJSIP_MSG
- * @{
- */
-typedef pjsip_generic_int_hdr pjsip_min_expires_hdr;
-
-/**
- * Create new Max-Forwards header instance.
- *
- * @param pool The pool.
- *
- * @return New Max-Forwards header instance.
- */
-PJ_DECL(pjsip_min_expires_hdr*) pjsip_min_expires_hdr_create(pj_pool_t *pool);
-
-
-/**
- * @}
- */
-
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR_ROUTING Header Field: Record-Route/Route
- * @brief Record-Route and Route header fields.
- * @ingroup PJSIP_MSG
- * @{
- */
-/**
- * Record-Route and Route headers.
- */
-typedef struct pjsip_routing_hdr
-{
- PJSIP_DECL_HDR_MEMBER(struct pjsip_routing_hdr); /**< Generic header fields. */
- pjsip_name_addr name_addr; /**< The URL in the Route/Record-Route header. */
- pj_str_t other_param; /** Other parameter. */
-} pjsip_routing_hdr;
-
-/** Alias for Record-Route header. */
-typedef pjsip_routing_hdr pjsip_rr_hdr;
-
-/** Alias for Route header. */
-typedef pjsip_routing_hdr pjsip_route_hdr;
-
-
-/**
- * Create new Record-Route header from the pool.
- *
- * @param pool The pool.
- * @return A new instance of Record-Route header.
- */
-PJ_DECL(pjsip_rr_hdr*) pjsip_rr_hdr_create( pj_pool_t *pool );
-
-/**
- * Create new Route header from the pool.
- *
- * @param pool The pool.
- * @return A new instance of "Route" header.
- */
-PJ_DECL(pjsip_route_hdr*) pjsip_route_hdr_create( pj_pool_t *pool );
-
-/**
- * Convert generic routing header to Record-Route header.
- *
- * @param r The generic routing header, or a "Routing" header.
- * @return Record-Route header.
- */
-PJ_DECL(pjsip_rr_hdr*) pjsip_routing_hdr_set_rr( pjsip_routing_hdr *r );
-
-/**
- * Convert generic routing header to "Route" header.
- *
- * @param r The generic routing header, or a "Record-Route" header.
- * @return "Route" header.
- */
-PJ_DECL(pjsip_route_hdr*) pjsip_routing_hdr_set_route( pjsip_routing_hdr *r );
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR_REQUIRE Header Field: Require
- * @brief Require header field.
- * @ingroup PJSIP_MSG
- * @{
- */
-typedef pjsip_generic_array_hdr pjsip_require_hdr;
-
-/**
- * Create new Require header instance.
- *
- * @param pool The pool.
- *
- * @return New Require header instance.
- */
-PJ_DECL(pjsip_require_hdr*) pjsip_require_hdr_create(pj_pool_t *pool);
-
-
-/**
- * @}
- */
-
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR_RETRY_AFTER Header Field: Retry-After
- * @brief Retry-After header field.
- * @ingroup PJSIP_MSG
- * @{
- */
-typedef pjsip_generic_int_hdr pjsip_retry_after_hdr;
-
-/**
- * Create new Retry-After header instance.
- *
- * @param pool The pool.
- *
- * @return New Retry-After header instance.
- */
-PJ_DECL(pjsip_retry_after_hdr*) pjsip_retry_after_hdr_create(pj_pool_t *pool);
-
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR_SUPPORTED Header Field: Supported
- * @brief Supported header field.
- * @ingroup PJSIP_MSG
- * @{
- */
-typedef pjsip_generic_array_hdr pjsip_supported_hdr;
-
-/**
- * Create new Supported header instance.
- *
- * @param pool The pool.
- *
- * @return New Supported header instance.
- */
-PJ_DECL(pjsip_supported_hdr*) pjsip_supported_hdr_create(pj_pool_t *pool);
-
-
-/**
- * @}
- */
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR_UNSUPPORTED Header Field: Unsupported
- * @brief Unsupported header field.
- * @ingroup PJSIP_MSG
- * @{
- */
-typedef pjsip_generic_array_hdr pjsip_unsupported_hdr;
-
-/**
- * Create new Unsupported header instance.
- *
- * @param pool The pool.
- *
- * @return New Unsupported header instance.
- */
-PJ_DECL(pjsip_unsupported_hdr*) pjsip_unsupported_hdr_create(pj_pool_t *pool);
-
-
-/**
- * @}
- */
-
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR_VIA Header Field: Via
- * @brief Via header field.
- * @ingroup PJSIP_MSG
- * @{
- */
-/**
- * SIP Via header.
- * In this implementation, Via header can only have one element in each header.
- * If a message arrives with multiple elements in a single Via, then they will
- * be split up into multiple Via headers.
- */
-typedef struct pjsip_via_hdr
-{
- PJSIP_DECL_HDR_MEMBER(struct pjsip_via_hdr);
- pj_str_t transport; /**< Transport type. */
- pjsip_host_port sent_by; /**< Host and optional port */
- int ttl_param; /**< TTL parameter, or -1 if it's not specified. */
- int rport_param; /**< "rport" parameter, 0 to specify without
- port number, -1 means doesn't exist. */
- pj_str_t maddr_param; /**< "maddr" parameter. */
- pj_str_t recvd_param; /**< "received" parameter. */
- pj_str_t branch_param; /**< "branch" parameter. */
- pj_str_t other_param; /**< Other parameters, concatenated as single string. */
- pj_str_t comment; /**< Comment. */
-} pjsip_via_hdr;
-
-/**
- * Create a new Via header.
- *
- * @param pool The pool.
- * @return A new "Via" header instance.
- */
-PJ_DECL(pjsip_via_hdr*) pjsip_via_hdr_create( pj_pool_t *pool );
-
-/**
- * @}
- */
-
-/**
- * @bug Once a header is put in the message, the header CAN NOT be put in
- * other list. Solution:
- * - always clone header in the message.
- * - create a list node for each header in the message.
- */
-
-
-///////////////////////////////////////////////////////////////////////////////
-/**
- * @defgroup PJSIP_MSG_HDR_UNIMP Unimplemented Header Fields
- * @brief Unimplemented header fields.
- * @ingroup PJSIP_MSG
- * @{
- */
-/** Accept-Encoding header. */
-typedef pjsip_generic_string_hdr pjsip_accept_encoding_hdr;
-
-/** Create Accept-Encoding header. */
-#define pjsip_accept_encoding_hdr_create pjsip_generic_string_hdr_create
-
-/** Accept-Language header. */
-typedef pjsip_generic_string_hdr pjsip_accept_lang_hdr;
-
-/** Create Accept-Language header. */
-#define pjsip_accept_lang_hdr_create pjsip_generic_string_hdr_create
-
-/** Alert-Info header. */
-typedef pjsip_generic_string_hdr pjsip_alert_info_hdr;
-
-/** Create Alert-Info header. */
-#define pjsip_alert_info_hdr_create pjsip_generic_string_hdr_create
-
-/** Authentication-Info header. */
-typedef pjsip_generic_string_hdr pjsip_auth_info_hdr;
-
-/** Create Authentication-Info header. */
-#define pjsip_auth_info_hdr_create pjsip_generic_string_hdr_create
-
-/** Call-Info header. */
-typedef pjsip_generic_string_hdr pjsip_call_info_hdr;
-
-/** Create Call-Info header. */
-#define pjsip_call_info_hdr_create pjsip_generic_string_hdr_create
-
-/** Content-Disposition header. */
-typedef pjsip_generic_string_hdr pjsip_content_disposition_hdr;
-
-/** Create Content-Disposition header. */
-#define pjsip_content_disposition_hdr_create pjsip_generic_string_hdr_create
-
-/** Content-Encoding header. */
-typedef pjsip_generic_string_hdr pjsip_content_encoding_hdr;
-
-/** Create Content-Encoding header. */
-#define pjsip_content_encoding_hdr_create pjsip_generic_string_hdr_create
-
-/** Content-Language header. */
-typedef pjsip_generic_string_hdr pjsip_content_lang_hdr;
-
-/** Create Content-Language header. */
-#define pjsip_content_lang_hdr_create pjsip_generic_string_hdr_create
-
-/** Date header. */
-typedef pjsip_generic_string_hdr pjsip_date_hdr;
-
-/** Create Date header. */
-#define pjsip_date_hdr_create pjsip_generic_string_hdr_create
-
-/** Error-Info header. */
-typedef pjsip_generic_string_hdr pjsip_err_info_hdr;
-
-/** Create Error-Info header. */
-#define pjsip_err_info_hdr_create pjsip_generic_string_hdr_create
-
-/** In-Reply-To header. */
-typedef pjsip_generic_string_hdr pjsip_in_reply_to_hdr;
-
-/** Create In-Reply-To header. */
-#define pjsip_in_reply_to_hdr_create pjsip_generic_string_hdr_create
-
-/** MIME-Version header. */
-typedef pjsip_generic_string_hdr pjsip_mime_version_hdr;
-
-/** Create MIME-Version header. */
-#define pjsip_mime_version_hdr_create pjsip_generic_string_hdr_create
-
-/** Organization header. */
-typedef pjsip_generic_string_hdr pjsip_organization_hdr;
-
-/** Create Organization header. */
-#define pjsip_organization_hdr_create pjsip_genric_string_hdr_create
-
-/** Priority header. */
-typedef pjsip_generic_string_hdr pjsip_priority_hdr;
-
-/** Create Priority header. */
-#define pjsip_priority_hdr_create pjsip_generic_string_hdr_create
-
-/** Proxy-Require header. */
-typedef pjsip_generic_string_hdr pjsip_proxy_require_hdr;
-
-/** Reply-To header. */
-typedef pjsip_generic_string_hdr pjsip_reply_to_hdr;
-
-/** Create Reply-To header. */
-#define pjsip_reply_to_hdr_create pjsip_generic_string_hdr_create
-
-/** Server header. */
-typedef pjsip_generic_string_hdr pjsip_server_hdr;
-
-/** Create Server header. */
-#define pjsip_server_hdr_create pjsip_generic_string_hdr_create
-
-/** Subject header. */
-typedef pjsip_generic_string_hdr pjsip_subject_hdr;
-
-/** Create Subject header. */
-#define pjsip_subject_hdr_create pjsip_generic_string_hdr_create
-
-/** Timestamp header. */
-typedef pjsip_generic_string_hdr pjsip_timestamp_hdr;
-
-/** Create Timestamp header. */
-#define pjsip_timestamp_hdr_create pjsip_generic_string_hdr_create
-
-/** User-Agent header. */
-typedef pjsip_generic_string_hdr pjsip_user_agent_hdr;
-
-/** Create User-Agent header. */
-#define pjsip_user_agent_hdr_create pjsip_generic_string_hdr_create
-
-/** Warning header. */
-typedef pjsip_generic_string_hdr pjsip_warning_hdr;
-
-/** Create Warning header. */
-#define pjsip_warning_hdr_create pjsip_generic_string_hdr_create
-
-/**
- * @}
- */
-
-/**
- * @} // PJSIP_MSG
- */
-
-/*
- * Include inline definitions.
- */
-#if PJ_FUNCTIONS_ARE_INLINED
-# include <pjsip/sip_msg_i.h>
-#endif
-
-
-PJ_END_DECL
-
-#endif /* __PJSIP_SIP_MSG_H__ */
-
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIP_MSG_H__ +#define __PJSIP_SIP_MSG_H__ + +/** + * @file sip_msg.h + * @brief SIP Message Structure. + */ + +#include <pjsip/sip_types.h> +#include <pjsip/sip_uri.h> +#include <pj/list.h> + +PJ_BEGIN_DECL + +/** + * @defgroup PJSIP_MSG SIP Message Structure + * @ingroup PJSIP + * @{ + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_METHOD Methods + * @brief Method names and manipulation. + * @ingroup PJSIP_MSG + * @{ + */ + +/** + * This enumeration declares SIP methods as described by RFC3261. Additional + * methods do exist, and they are described by corresponding RFCs for the SIP + * extentensions. Since they won't alter the characteristic of the processing + * of the message, they don't need to be explicitly mentioned here. + */ +typedef enum pjsip_method_e +{ + /** INVITE method, for establishing dialogs. */ + PJSIP_INVITE_METHOD, + + /** CANCEL method, for cancelling request. */ + PJSIP_CANCEL_METHOD, + + /** ACK method, for acknowledging final response to INVITE. */ + PJSIP_ACK_METHOD, + + /** BYE method, for terminating dialog. */ + PJSIP_BYE_METHOD, + + /** REGISTER method. */ + PJSIP_REGISTER_METHOD, + + /** OPTIONS method, for querying remote capabilities. */ + PJSIP_OPTIONS_METHOD, + + /** Other method, which means that the method name itself will be stored + elsewhere. */ + PJSIP_OTHER_METHOD, + +} pjsip_method_e; + + + +/** + * This structure represents a SIP method. + * Application must always use either #pjsip_method_init or #pjsip_method_set + * to make sure that method name is initialized correctly. This way, the name + * member will always contain a valid method string regardless whether the ID + * is recognized or not. + */ +typedef struct pjsip_method +{ + pjsip_method_e id; /**< Method ID, from \a pjsip_method_e. */ + pj_str_t name; /**< Method name, which will always contain the + method string. */ +} pjsip_method; + + +/** + * Initialize the method structure from a string. + * This function will check whether the method is a known method then set + * both the id and name accordingly. + * + * @param m The method to initialize. + * @param pool Pool where memory allocation will be allocated from, if required. + * @param str The method string. + */ +PJ_DECL(void) pjsip_method_init( pjsip_method *m, + pj_pool_t *pool, + const pj_str_t *str); + +/** + * Initialize the method structure from a string, without cloning the string. + * See #pjsip_method_init. + * + * @param m The method structure to be initialized. + * @param str The method string. + */ +PJ_DECL(void) pjsip_method_init_np( pjsip_method *m, + pj_str_t *str); + +/** + * Set the method with the predefined method ID. + * This function will also set the name member of the structure to the correct + * string according to the method. + * + * @param m The method structure. + * @param id The method ID. + */ +PJ_DECL(void) pjsip_method_set( pjsip_method *m, pjsip_method_e id ); + + +/** + * Copy one method structure to another. If the method is of the known methods, + * then memory allocation is not required. + * + * @param pool Pool to allocate memory from, if required. + * @param method The destination method to copy to. + * @param rhs The source method to copy from. + */ +PJ_DECL(void) pjsip_method_copy( pj_pool_t *pool, + pjsip_method *method, + const pjsip_method *rhs ); + +/** + * Compare one method with another, and conveniently determine whether the + * first method is equal, less than, or greater than the second method. + * + * @param m1 The first method. + * @param m2 The second method. + * + * @return Zero if equal, otherwise will return -1 if less or +1 if greater. + */ +PJ_DECL(int) pjsip_method_cmp( const pjsip_method *m1, const pjsip_method *m2); + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR Header Fields General Structure. + * @brief General Header Fields Structure. + * @ingroup PJSIP_MSG + * @{ + */ + +/** + * Header types, as defined by RFC3261. + */ +typedef enum pjsip_hdr_e +{ + /* + * These are the headers documented in RFC3261. Headers not documented + * there must have type PJSIP_H_OTHER, and the header type itself is + * recorded in the header name string. + * + * DO NOT CHANGE THE VALUE/ORDER OF THE HEADER IDs!!!. + */ + PJSIP_H_ACCEPT, + PJSIP_H_ACCEPT_ENCODING_UNIMP, + PJSIP_H_ACCEPT_LANGUAGE_UNIMP, + PJSIP_H_ALERT_INFO_UNIMP, + PJSIP_H_ALLOW, + PJSIP_H_AUTHENTICATION_INFO_UNIMP, + PJSIP_H_AUTHORIZATION, + PJSIP_H_CALL_ID, + PJSIP_H_CALL_INFO_UNIMP, + PJSIP_H_CONTACT, + PJSIP_H_CONTENT_DISPOSITION_UNIMP, + PJSIP_H_CONTENT_ENCODING_UNIMP, + PJSIP_H_CONTENT_LANGUAGE_UNIMP, + PJSIP_H_CONTENT_LENGTH, + PJSIP_H_CONTENT_TYPE, + PJSIP_H_CSEQ, + PJSIP_H_DATE_UNIMP, + PJSIP_H_ERROR_INFO_UNIMP, + PJSIP_H_EXPIRES, + PJSIP_H_FROM, + PJSIP_H_IN_REPLY_TO_UNIMP, + PJSIP_H_MAX_FORWARDS, + PJSIP_H_MIME_VERSION_UNIMP, + PJSIP_H_MIN_EXPIRES, + PJSIP_H_ORGANIZATION_UNIMP, + PJSIP_H_PRIORITY_UNIMP, + PJSIP_H_PROXY_AUTHENTICATE, + PJSIP_H_PROXY_AUTHORIZATION, + PJSIP_H_PROXY_REQUIRE_UNIMP, + PJSIP_H_RECORD_ROUTE, + PJSIP_H_REPLY_TO_UNIMP, + PJSIP_H_REQUIRE, + PJSIP_H_RETRY_AFTER, + PJSIP_H_ROUTE, + PJSIP_H_SERVER_UNIMP, + PJSIP_H_SUBJECT_UNIMP, + PJSIP_H_SUPPORTED, + PJSIP_H_TIMESTAMP_UNIMP, + PJSIP_H_TO, + PJSIP_H_UNSUPPORTED, + PJSIP_H_USER_AGENT_UNIMP, + PJSIP_H_VIA, + PJSIP_H_WARNING_UNIMP, + PJSIP_H_WWW_AUTHENTICATE, + + PJSIP_H_OTHER, + +} pjsip_hdr_e; + +/** + * This structure provides the pointer to basic functions that are needed + * for generic header operations. All header fields will have pointer to + * this structure, so that they can be manipulated uniformly. + */ +typedef struct pjsip_hdr_vptr +{ + /** + * Function to clone the header. + * + * @param pool Memory pool to allocate the new header. + * @param hdr Header to clone. + * + * @return A new instance of the header. + */ + void *(*clone)(pj_pool_t *pool, const void *hdr); + + /** + * Pointer to function to shallow clone the header. + * Shallow cloning will just make a memory copy of the original header, + * thus all pointers in original header will be kept intact. Because the + * function does not need to perform deep copy, the operation should be + * faster, but the application must make sure that the original header + * is still valid throughout the lifetime of new header. + * + * @param pool Memory pool to allocate the new header. + * @param hdr The header to clone. + */ + void *(*shallow_clone)(pj_pool_t *pool, const void *hdr); + + /** Pointer to function to print the header to the specified buffer. + * Returns the length of string written, or -1 if the remaining buffer + * is not enough to hold the header. + * + * @param hdr The header to print. + * @param buf The buffer. + * @param len The size of the buffer. + * + * @return The size copied to buffer, or -1 if there's not enough space. + */ + int (*print_on)(void *hdr, char *buf, pj_size_t len); + +} pjsip_hdr_vptr; + + +/** + * Generic fields for all SIP headers are declared using this macro, to make + * sure that all headers will have exactly the same layout in their start of + * the storage. This behaves like C++ inheritance actually. + */ +#define PJSIP_DECL_HDR_MEMBER(hdr) \ + /** List members. */ \ + PJ_DECL_LIST_MEMBER(hdr); \ + /** Header type */ \ + pjsip_hdr_e type; \ + /** Header name. */ \ + pj_str_t name; \ + /** Header short name version. */ \ + pj_str_t sname; \ + /** Virtual function table. */ \ + pjsip_hdr_vptr *vptr + + +/** + * Generic SIP header structure, for generic manipulation for headers in the + * message. All header fields can be typecasted to this type. + */ +struct pjsip_hdr +{ + PJSIP_DECL_HDR_MEMBER(struct pjsip_hdr); +}; + + +/** + * This generic function will clone any header, by calling "clone" function + * in header's virtual function table. + * + * @param pool The pool to allocate memory from. + * @param hdr The header to clone. + * + * @return A new instance copied from the original header. + */ +PJ_DECL(void*) pjsip_hdr_clone( pj_pool_t *pool, const void *hdr ); + + +/** + * This generic function will clone any header, by calling "shallow_clone" + * function in header's virtual function table. + * + * @param pool The pool to allocate memory from. + * @param hdr The header to clone. + * + * @return A new instance copied from the original header. + */ +PJ_DECL(void*) pjsip_hdr_shallow_clone( pj_pool_t *pool, const void *hdr ); + +/** + * This generic function will print any header, by calling "print" + * function in header's virtual function table. + * + * @param hdr The header to print. + * @param buf The buffer. + * @param len The size of the buffer. + * + * @return The size copied to buffer, or -1 if there's not enough space. + */ +PJ_DECL(int) pjsip_hdr_print_on( void *hdr, char *buf, pj_size_t len); + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_LINE Request and Status Line. + * @brief Request and status line structures and manipulation. + * @ingroup PJSIP_MSG + * @{ + */ + +/** + * This structure describes SIP request line. + */ +typedef struct pjsip_request_line +{ + pjsip_method method; /**< Method for this request line. */ + pjsip_uri *uri; /**< URI for this request line. */ +} pjsip_request_line; + + +/** + * This structure describes SIP status line. + */ +typedef struct pjsip_status_line +{ + int code; /**< Status code. */ + pj_str_t reason; /**< Reason string. */ +} pjsip_status_line; + + +/** + * This enumeration lists standard SIP status codes according to RFC 3261. + * In addition, it also declares new status class 7xx for errors generated + * by the stack. This status class however should not get transmitted on the + * wire. + */ +typedef enum pjsip_status_code +{ + PJSIP_SC_TRYING = 100, + PJSIP_SC_RINGING = 180, + PJSIP_SC_CALL_BEING_FORWARDED = 181, + PJSIP_SC_QUEUED = 182, + PJSIP_SC_PROGRESS = 183, + + PJSIP_SC_OK = 200, + + PJSIP_SC_MULTIPLE_CHOICES = 300, + PJSIP_SC_MOVED_PERMANENTLY = 301, + PJSIP_SC_MOVED_TEMPORARILY = 302, + PJSIP_SC_USE_PROXY = 305, + PJSIP_SC_ALTERNATIVE_SERVICE = 380, + + PJSIP_SC_BAD_REQUEST = 400, + PJSIP_SC_UNAUTHORIZED = 401, + PJSIP_SC_PAYMENT_REQUIRED = 402, + PJSIP_SC_FORBIDDEN = 403, + PJSIP_SC_NOT_FOUND = 404, + PJSIP_SC_METHOD_NOT_ALLOWED = 405, + PJSIP_SC_NOT_ACCEPTABLE = 406, + PJSIP_SC_PROXY_AUTHENTICATION_REQUIRED = 407, + PJSIP_SC_REQUEST_TIMEOUT = 408, + PJSIP_SC_GONE = 410, + PJSIP_SC_REQUEST_ENTITY_TOO_LARGE = 413, + PJSIP_SC_REQUEST_URI_TOO_LONG = 414, + PJSIP_SC_UNSUPPORTED_MEDIA_TYPE = 415, + PJSIP_SC_UNSUPPORTED_URI_SCHEME = 416, + PJSIP_SC_BAD_EXTENSION = 420, + PJSIP_SC_EXTENSION_REQUIRED = 421, + PJSIP_SC_INTERVAL_TOO_BRIEF = 423, + PJSIP_SC_TEMPORARILY_UNAVAILABLE = 480, + PJSIP_SC_CALL_TSX_DOES_NOT_EXIST = 481, + PJSIP_SC_LOOP_DETECTED = 482, + PJSIP_SC_TOO_MANY_HOPS = 483, + PJSIP_SC_ADDRESS_INCOMPLETE = 484, + PJSIP_AC_AMBIGUOUS = 485, + PJSIP_SC_BUSY_HERE = 486, + PJSIP_SC_REQUEST_TERMINATED = 487, + PJSIP_SC_NOT_ACCEPTABLE_HERE = 488, + PJSIP_SC_REQUEST_PENDING = 491, + PJSIP_SC_UNDECIPHERABLE = 493, + + PJSIP_SC_INTERNAL_SERVER_ERROR = 500, + PJSIP_SC_NOT_IMPLEMENTED = 501, + PJSIP_SC_BAD_GATEWAY = 502, + PJSIP_SC_SERVICE_UNAVAILABLE = 503, + PJSIP_SC_SERVER_TIMEOUT = 504, + PJSIP_SC_VERSION_NOT_SUPPORTED = 505, + PJSIP_SC_MESSAGE_TOO_LARGE = 513, + + PJSIP_SC_BUSY_EVERYWHERE = 600, + PJSIP_SC_DECLINE = 603, + PJSIP_SC_DOES_NOT_EXIST_ANYWHERE = 604, + PJSIP_SC_NOT_ACCEPTABLE_ANYWHERE = 606, + + PJSIP_SC_TSX_TIMEOUT = 701, + PJSIP_SC_TSX_RESOLVE_ERROR = 702, + PJSIP_SC_TSX_TRANSPORT_ERROR = 703, + +} pjsip_status_code; + +/** + * Get the default status text for the status code. + * + * @param status_code SIP Status Code + * + * @return textual message for the status code. + */ +PJ_DECL(const pj_str_t*) pjsip_get_status_text(int status_code); + +/** + * This macro returns non-zero (TRUE) if the specified status_code is + * in the same class as the code_class. + * + * @param status_code The status code. + * @param code_class The status code in the class (for example 100, 200). + */ +#define PJSIP_IS_STATUS_IN_CLASS(status_code, code_class) \ + (status_code/100 == code_class/100) + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @addtogroup PJSIP_MSG_MEDIA Media Type + * @brief Media type definitions and manipulations. + * @ingroup PJSIP_MSG + * @{ + */ + +/** + * This structure describes SIP media type, as used for example in + * Accept and Content-Type header.. + */ +typedef struct pjsip_media_type +{ + pj_str_t type; /**< Media type. */ + pj_str_t subtype; /**< Media subtype. */ + pj_str_t param; /**< Media type parameters (concatenated). */ +} pjsip_media_type; + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @addtogroup PJSIP_MSG_BODY Message Body + * @brief SIP message body structures and manipulation. + * @ingroup PJSIP_MSG + * @{ + */ + +/** + * Generic abstraction to message body. + * When an incoming message is parsed (pjsip_parse_msg()), the parser fills in + * all members with the appropriate value. The 'data' and 'len' member will + * describe portion of incoming packet which denotes the message body. + * When application needs to attach message body to outgoing SIP message, it + * must fill in all members of this structure. + */ +typedef struct pjsip_msg_body +{ + /** MIME content type. + * For incoming messages, the parser will fill in this member with the + * content type found in Content-Type header. + * + * For outgoing messages, application must fill in this member with + * appropriate value, because the stack will generate Content-Type header + * based on the value specified here. + */ + pjsip_media_type content_type; + + /** Pointer to buffer which holds the message body data. + * For incoming messages, the parser will fill in this member with the + * pointer to the body string. + * + * When sending outgoing message, this member doesn't need to point to the + * actual message body string. It can be assigned with arbitrary pointer, + * because the value will only need to be understood by the print_body() + * function. The stack itself will not try to interpret this value, but + * instead will always call the print_body() whenever it needs to get the + * actual body string. + */ + void *data; + + /** The length of the data. + * For incoming messages, the parser will fill in this member with the + * actual length of message body. + * + * When sending outgoing message, again just like the "data" member, the + * "len" member doesn't need to point to the actual length of the body + * string. + */ + unsigned len; + + /** Pointer to function to print this message body. + * Application must set a proper function here when sending outgoing + * message. + * + * @param msg_body This structure itself. + * @param buf The buffer. + * @param size The buffer size. + * + * @return The length of the string printed, or -1 if there is + * not enough space in the buffer to print the whole + * message body. + */ + int (*print_body)(struct pjsip_msg_body *msg_body, + char *buf, pj_size_t size); + +} pjsip_msg_body; + +/** + * General purpose function to textual data in a SIP body. Attach this function + * in a SIP message body only if the data in pjsip_msg_body is a textual + * message ready to be embedded in a SIP message. If the data in the message + * body is not a textual body, then application must supply a custom function + * to print that body. + * + * @param msg_body The message body. + * @param buf Buffer to copy the message body to. + * @param size The size of the buffer. + * + * @return The length copied to the buffer, or -1. + */ +PJ_DECL(int) pjsip_print_text_body( pjsip_msg_body *msg_body, + char *buf, pj_size_t size); + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_MSG Message Structure + * @brief Message structure and operations. + * @ingroup PJSIP_MSG + * @{ + */ + +/** + * Message type (request or response). + */ +typedef enum pjsip_msg_type_e +{ + PJSIP_REQUEST_MSG, /**< Indicates request message. */ + PJSIP_RESPONSE_MSG, /**< Indicates response message. */ +} pjsip_msg_type_e; + + +/** + * This structure describes a SIP message. + */ +struct pjsip_msg +{ + /** Message type (ie request or response). */ + pjsip_msg_type_e type; + + /** The first line of the message can be either request line for request + * messages, or status line for response messages. It is represented here + * as a union. + */ + union + { + /** Request Line. */ + struct pjsip_request_line req; + + /** Status Line. */ + struct pjsip_status_line status; + } line; + + /** List of message headers. */ + pjsip_hdr hdr; + + /** Pointer to message body, or NULL if no message body is attached to + * this mesage. + */ + pjsip_msg_body *body; +}; + + +/** + * Create new request or response message. + * + * @param pool The pool. + * @param type Message type. + * @return New message, or THROW exception if failed. + */ +PJ_DECL(pjsip_msg*) pjsip_msg_create( pj_pool_t *pool, pjsip_msg_type_e type); + +/** + * Find a header in the message by the header type. + * + * @param msg The message. + * @param type The header type to find. + * @param start The first header field where the search should begin. + * If NULL is specified, then the search will begin from the + * first header, otherwise the search will begin at the + * specified header. + * + * @return The header field, or NULL if no header with the specified + * type is found. + */ +PJ_DECL(void*) pjsip_msg_find_hdr( pjsip_msg *msg, + pjsip_hdr_e type, void *start); + +/** + * Find a header in the message by its name. + * + * @param msg The message. + * @param name The header name to find. + * @param start The first header field where the search should begin. + * If NULL is specified, then the search will begin from the + * first header, otherwise the search will begin at the + * specified header. + * + * @return The header field, or NULL if no header with the specified + * type is found. + */ +PJ_DECL(void*) pjsip_msg_find_hdr_by_name( pjsip_msg *msg, + const pj_str_t *name, void *start); + +/** + * Find and remove a header in the message. + * + * @param msg The message. + * @param hdr The header type to find. + * @param start The first header field where the search should begin, + * or NULL to search from the first header in the message. + * + * @return The header field, or NULL if not found. + */ +PJ_DECL(void*) pjsip_msg_find_remove_hdr( pjsip_msg *msg, + pjsip_hdr_e hdr, void *start); + +/** + * Add a header to the message, putting it last in the header list. + * + * @param msg The message. + * @param hdr The header to add. + * + * @bug Once the header is put in a list (or message), it can not be put in + * other list (or message). Otherwise Real Bad Thing will happen. + */ +PJ_IDECL(void) pjsip_msg_add_hdr( pjsip_msg *msg, pjsip_hdr *hdr ); + +/** + * Add header field to the message, putting it in the front of the header list. + * + * @param msg The message. + * @param hdr The header to add. + * + * @bug Once the header is put in a list (or message), it can not be put in + * other list (or message). Otherwise Real Bad Thing will happen. + */ +PJ_IDECL(void) pjsip_msg_insert_first_hdr( pjsip_msg *msg, pjsip_hdr *hdr ); + +/** + * Print the message to the specified buffer. + * + * @param msg The message to print. + * @param buf The buffer + * @param size The size of the buffer. + * + * @return The length of the printed characters (in bytes), or NEGATIVE + * value if the message is too large for the specified buffer. + */ +PJ_DECL(pj_ssize_t) pjsip_msg_print(pjsip_msg *msg, char *buf, pj_size_t size); + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @addtogroup PJSIP_MSG_HDR_GEN Header Field: Generic + * @brief Generic header field which contains header name and value. + * @ingroup PJSIP_MSG + * @{ + */ + +/** + * Generic SIP header, which contains hname and a string hvalue. + * Note that this header is not supposed to be used as 'base' class for headers. + */ +typedef struct pjsip_generic_string_hdr +{ + PJSIP_DECL_HDR_MEMBER(struct pjsip_generic_string_hdr); /**< Standard header field. */ + pj_str_t hvalue; /**< hvalue */ +} pjsip_generic_string_hdr; + + +/** + * Create a new instance of generic header. A generic header can have an + * arbitrary header name. + * + * @param pool The pool. + * @param hname The header name to be assigned to the header, or NULL to + * assign the header name with some string. + * + * @return The header, or THROW exception. + */ +PJ_DECL(pjsip_generic_string_hdr*) pjsip_generic_string_hdr_create( pj_pool_t *pool, + const pj_str_t *hname ); + +/** + * Create a generic header along with the text content. + * + * @param pool The pool. + * @param hname The header name. + * @param hvalue The header text content. + * + * @return The header instance. + */ +PJ_DECL(pjsip_generic_string_hdr*) +pjsip_generic_string_hdr_create_with_text( pj_pool_t *pool, + const pj_str_t *hname, + const pj_str_t *hvalue); + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @addtogroup PJSIP_MSG_HDR_GEN_INT Header Field: Generic Integer + * @brief Generic header field which contains header name and value. + * @ingroup PJSIP_MSG + * @{ + */ + +/** + * Generic SIP header, which contains hname and a string hvalue. + */ +typedef struct pjsip_generic_int_hdr +{ + PJSIP_DECL_HDR_MEMBER(struct pjsip_generic_int_hdr); /**< Standard header field. */ + pj_int32_t ivalue; /**< ivalue */ +} pjsip_generic_int_hdr; + + +/** + * Create a new instance of generic header. A generic header can have an + * arbitrary header name. + * + * @param pool The pool. + * @param hname The header name to be assigned to the header, or NULL to + * assign the header name with some string. + * + * @return The header, or THROW exception. + */ +PJ_DECL(pjsip_generic_int_hdr*) pjsip_generic_int_hdr_create( pj_pool_t *pool, + const pj_str_t *hname ); + +/** + * Create a generic header along with the value. + * + * @param pool The pool. + * @param hname The header name. + * @param value The header value content. + * + * @return The header instance. + */ +PJ_DECL(pjsip_generic_int_hdr*) +pjsip_generic_int_hdr_create_with_value( pj_pool_t *pool, + const pj_str_t *hname, + int value); + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR_GENERIC_LIST Header Field: Generic string list. + * @brief Header with list of strings separated with comma + * @ingroup PJSIP_MSG + * @{ + */ + +/** Maximum elements in the header array. */ +#define PJSIP_GENERIC_ARRAY_MAX_COUNT 32 + +typedef struct pjsip_generic_array_hdr +{ + PJSIP_DECL_HDR_MEMBER(struct pjsip_generic_array_hdr); + unsigned count; /**< Number of elements. */ + pj_str_t values[PJSIP_GENERIC_ARRAY_MAX_COUNT]; /**< Elements. */ +} pjsip_generic_array_hdr; + +/** + * Create generic array header. + * + * @param pool Pool to allocate memory from. + * + * @return New generic array header. + */ +PJ_DECL(pjsip_generic_array_hdr*) pjsip_generic_array_create(pj_pool_t *pool, + const pj_str_t *hnames); + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR_ACCEPT Header Field: Accept + * @brief Accept header field. + * @ingroup PJSIP_MSG + * @{ + */ +/** Accept header. */ +typedef pjsip_generic_array_hdr pjsip_accept_hdr; + +/** Maximum fields in Accept header. */ +#define PJSIP_MAX_ACCEPT_COUNT PJSIP_GENERIC_ARRAY_MAX_COUNT + +/** + * Create new Accept header instance. + * + * @param pool The pool. + * + * @return New Accept header instance. + */ +PJ_DECL(pjsip_accept_hdr*) pjsip_accept_hdr_create(pj_pool_t *pool); + + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR_ALLOW Header Field: Allow + * @brief Allow header field. + * @ingroup PJSIP_MSG + * @{ + */ +typedef pjsip_generic_array_hdr pjsip_allow_hdr; + +/** + * Create new Allow header instance. + * + * @param pool The pool. + * + * @return New Allow header instance. + */ +PJ_DECL(pjsip_allow_hdr*) pjsip_allow_hdr_create(pj_pool_t *pool); + + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR_CID Header Field: Call-ID + * @brief Call-ID header field. + * @ingroup PJSIP_MSG + * @{ + */ +/** + * Call-ID header. + */ +typedef struct pjsip_cid_hdr +{ + PJSIP_DECL_HDR_MEMBER(struct pjsip_cid_hdr); + pj_str_t id; /**< Call-ID string. */ +} pjsip_cid_hdr; + + +/** + * Create new Call-ID header. + * + * @param pool The pool. + * + * @return new Call-ID header. + */ +PJ_DECL(pjsip_cid_hdr*) pjsip_cid_hdr_create( pj_pool_t *pool ); + + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR_CLEN Header Field: Content-Length + * @brief Content-Length header field. + * @ingroup PJSIP_MSG + * @{ + */ +/** + * Content-Length header. + */ +typedef struct pjsip_clen_hdr +{ + PJSIP_DECL_HDR_MEMBER(struct pjsip_clen_hdr); + int len; /**< Content length. */ +} pjsip_clen_hdr; + +/** + * Create new Content-Length header. + * + * @param pool the pool. + * @return A new Content-Length header instance. + */ +PJ_DECL(pjsip_clen_hdr*) pjsip_clen_hdr_create( pj_pool_t *pool ); + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR_CSEQ Header Field: CSeq + * @brief CSeq header field. + * @ingroup PJSIP_MSG + * @{ + */ +/** + * CSeq header. + */ +typedef struct pjsip_cseq_hdr +{ + PJSIP_DECL_HDR_MEMBER(struct pjsip_cseq_hdr); + int cseq; /**< CSeq number. */ + pjsip_method method; /**< CSeq method. */ +} pjsip_cseq_hdr; + + +/** Create new CSeq header. + * + * @param pool The pool. + * @return A new CSeq header instance. + */ +PJ_DECL(pjsip_cseq_hdr*) pjsip_cseq_hdr_create( pj_pool_t *pool ); + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR_CONTACT Header Field: Contact + * @brief Contact header field. + * @ingroup PJSIP_MSG + * @{ + */ +/** + * Contact header. + * In this library, contact header only contains single URI. If a message has + * multiple URI in the Contact header, the URI will be put in separate Contact + * headers. + */ +typedef struct pjsip_contact_hdr +{ + PJSIP_DECL_HDR_MEMBER(struct pjsip_contact_hdr); + int star; /**< The contact contains only a '*' character */ + pjsip_uri *uri; /**< URI in the contact. */ + int q1000; /**< The "q" value times 1000 (to avoid float) */ + pj_int32_t expires; /**< Expires parameter, otherwise -1 if not present. */ + pjsip_param other_param; /**< Other parameters, concatenated in a single string. */ +} pjsip_contact_hdr; + + +/** + * Create a new Contact header. + * + * @param pool The pool. + * @return A new instance of Contact header. + */ +PJ_DECL(pjsip_contact_hdr*) pjsip_contact_hdr_create( pj_pool_t *pool ); + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR_CTYPE Header Field: Content-Type + * @brief Content-Type header field. + * @ingroup PJSIP_MSG + * @{ + */ +/** + * Content-Type. + */ +typedef struct pjsip_ctype_hdr +{ + PJSIP_DECL_HDR_MEMBER(struct pjsip_ctype_hdr); + pjsip_media_type media; /**< Media type. */ +} pjsip_ctype_hdr; + + +/** + * Create a nwe Content Type header. + * + * @param pool The pool. + * @return A new Content-Type header. + */ +PJ_DECL(pjsip_ctype_hdr*) pjsip_ctype_hdr_create( pj_pool_t *pool ); + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR_EXPIRES Header Field: Expires + * @brief Expires header field. + * @ingroup PJSIP_MSG + * @{ + */ +/** Expires header. */ +typedef pjsip_generic_int_hdr pjsip_expires_hdr; + +/** + * Create a new Expires header. + * + * @param pool The pool. + * @return A new Expires header. + */ +PJ_DECL(pjsip_expires_hdr*) pjsip_expires_hdr_create( pj_pool_t *pool ); + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR_FROMTO Header Field: From/To + * @brief From and To header field. + * @ingroup PJSIP_MSG + * @{ + */ +/** + * To or From header. + */ +typedef struct pjsip_fromto_hdr +{ + PJSIP_DECL_HDR_MEMBER(struct pjsip_fromto_hdr); + pjsip_uri *uri; /**< URI in From/To header. */ + pj_str_t tag; /**< Header "tag" parameter. */ + pjsip_param other_param; /**< Other params, concatenated as a single string. */ +} pjsip_fromto_hdr; + +/** Alias for From header. */ +typedef pjsip_fromto_hdr pjsip_from_hdr; + +/** Alias for To header. */ +typedef pjsip_fromto_hdr pjsip_to_hdr; + +/** + * Create a From header. + * + * @param pool The pool. + * @return New instance of From header. + */ +PJ_DECL(pjsip_from_hdr*) pjsip_from_hdr_create( pj_pool_t *pool ); + +/** + * Create a To header. + * + * @param pool The pool. + * @return New instance of To header. + */ +PJ_DECL(pjsip_to_hdr*) pjsip_to_hdr_create( pj_pool_t *pool ); + +/** + * Convert the header to a From header. + * + * @param pool The pool. + * @return "From" header. + */ +PJ_DECL(pjsip_from_hdr*) pjsip_fromto_set_from( pjsip_fromto_hdr *hdr ); + +/** + * Convert the header to a To header. + * + * @param pool The pool. + * @return "To" header. + */ +PJ_DECL(pjsip_to_hdr*) pjsip_fromto_set_to( pjsip_fromto_hdr *hdr ); + +/** + * @} + */ + + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR_MAX_FORWARDS Header Field: Max-Forwards + * @brief Max-Forwards header field. + * @ingroup PJSIP_MSG + * @{ + */ +typedef pjsip_generic_int_hdr pjsip_max_forwards_hdr; + +/** + * Create new Max-Forwards header instance. + * + * @param pool The pool. + * + * @return New Max-Forwards header instance. + */ +PJ_DECL(pjsip_max_forwards_hdr*) pjsip_max_forwards_hdr_create(pj_pool_t *pool); + + +/** + * @} + */ + + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR_MIN_EXPIRES Header Field: Min-Expires + * @brief Min-Expires header field. + * @ingroup PJSIP_MSG + * @{ + */ +typedef pjsip_generic_int_hdr pjsip_min_expires_hdr; + +/** + * Create new Max-Forwards header instance. + * + * @param pool The pool. + * + * @return New Max-Forwards header instance. + */ +PJ_DECL(pjsip_min_expires_hdr*) pjsip_min_expires_hdr_create(pj_pool_t *pool); + + +/** + * @} + */ + + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR_ROUTING Header Field: Record-Route/Route + * @brief Record-Route and Route header fields. + * @ingroup PJSIP_MSG + * @{ + */ +/** + * Record-Route and Route headers. + */ +typedef struct pjsip_routing_hdr +{ + PJSIP_DECL_HDR_MEMBER(struct pjsip_routing_hdr); /**< Generic header fields. */ + pjsip_name_addr name_addr; /**< The URL in the Route/Record-Route header. */ + pjsip_param other_param; /** Other parameter. */ +} pjsip_routing_hdr; + +/** Alias for Record-Route header. */ +typedef pjsip_routing_hdr pjsip_rr_hdr; + +/** Alias for Route header. */ +typedef pjsip_routing_hdr pjsip_route_hdr; + + +/** + * Create new Record-Route header from the pool. + * + * @param pool The pool. + * @return A new instance of Record-Route header. + */ +PJ_DECL(pjsip_rr_hdr*) pjsip_rr_hdr_create( pj_pool_t *pool ); + +/** + * Create new Route header from the pool. + * + * @param pool The pool. + * @return A new instance of "Route" header. + */ +PJ_DECL(pjsip_route_hdr*) pjsip_route_hdr_create( pj_pool_t *pool ); + +/** + * Convert generic routing header to Record-Route header. + * + * @param r The generic routing header, or a "Routing" header. + * @return Record-Route header. + */ +PJ_DECL(pjsip_rr_hdr*) pjsip_routing_hdr_set_rr( pjsip_routing_hdr *r ); + +/** + * Convert generic routing header to "Route" header. + * + * @param r The generic routing header, or a "Record-Route" header. + * @return "Route" header. + */ +PJ_DECL(pjsip_route_hdr*) pjsip_routing_hdr_set_route( pjsip_routing_hdr *r ); + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR_REQUIRE Header Field: Require + * @brief Require header field. + * @ingroup PJSIP_MSG + * @{ + */ +typedef pjsip_generic_array_hdr pjsip_require_hdr; + +/** + * Create new Require header instance. + * + * @param pool The pool. + * + * @return New Require header instance. + */ +PJ_DECL(pjsip_require_hdr*) pjsip_require_hdr_create(pj_pool_t *pool); + + +/** + * @} + */ + + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR_RETRY_AFTER Header Field: Retry-After + * @brief Retry-After header field. + * @ingroup PJSIP_MSG + * @{ + */ +typedef pjsip_generic_int_hdr pjsip_retry_after_hdr; + +/** + * Create new Retry-After header instance. + * + * @param pool The pool. + * + * @return New Retry-After header instance. + */ +PJ_DECL(pjsip_retry_after_hdr*) pjsip_retry_after_hdr_create(pj_pool_t *pool); + + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR_SUPPORTED Header Field: Supported + * @brief Supported header field. + * @ingroup PJSIP_MSG + * @{ + */ +typedef pjsip_generic_array_hdr pjsip_supported_hdr; + +/** + * Create new Supported header instance. + * + * @param pool The pool. + * + * @return New Supported header instance. + */ +PJ_DECL(pjsip_supported_hdr*) pjsip_supported_hdr_create(pj_pool_t *pool); + + +/** + * @} + */ + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR_UNSUPPORTED Header Field: Unsupported + * @brief Unsupported header field. + * @ingroup PJSIP_MSG + * @{ + */ +typedef pjsip_generic_array_hdr pjsip_unsupported_hdr; + +/** + * Create new Unsupported header instance. + * + * @param pool The pool. + * + * @return New Unsupported header instance. + */ +PJ_DECL(pjsip_unsupported_hdr*) pjsip_unsupported_hdr_create(pj_pool_t *pool); + + +/** + * @} + */ + + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR_VIA Header Field: Via + * @brief Via header field. + * @ingroup PJSIP_MSG + * @{ + */ +/** + * SIP Via header. + * In this implementation, Via header can only have one element in each header. + * If a message arrives with multiple elements in a single Via, then they will + * be split up into multiple Via headers. + */ +typedef struct pjsip_via_hdr +{ + PJSIP_DECL_HDR_MEMBER(struct pjsip_via_hdr); + pj_str_t transport; /**< Transport type. */ + pjsip_host_port sent_by; /**< Host and optional port */ + int ttl_param; /**< TTL parameter, or -1 if it's not specified. */ + int rport_param; /**< "rport" parameter, 0 to specify without + port number, -1 means doesn't exist. */ + pj_str_t maddr_param; /**< "maddr" parameter. */ + pj_str_t recvd_param; /**< "received" parameter. */ + pj_str_t branch_param; /**< "branch" parameter. */ + pjsip_param other_param; /**< Other parameters, concatenated as single string. */ + pj_str_t comment; /**< Comment. */ +} pjsip_via_hdr; + +/** + * Create a new Via header. + * + * @param pool The pool. + * @return A new "Via" header instance. + */ +PJ_DECL(pjsip_via_hdr*) pjsip_via_hdr_create( pj_pool_t *pool ); + +/** + * @} + */ + +/** + * @bug Once a header is put in the message, the header CAN NOT be put in + * other list. Solution: + * - always clone header in the message. + * - create a list node for each header in the message. + */ + + +/////////////////////////////////////////////////////////////////////////////// +/** + * @defgroup PJSIP_MSG_HDR_UNIMP Unimplemented Header Fields + * @brief Unimplemented header fields. + * @ingroup PJSIP_MSG + * @{ + */ +/** Accept-Encoding header. */ +typedef pjsip_generic_string_hdr pjsip_accept_encoding_hdr; + +/** Create Accept-Encoding header. */ +#define pjsip_accept_encoding_hdr_create pjsip_generic_string_hdr_create + +/** Accept-Language header. */ +typedef pjsip_generic_string_hdr pjsip_accept_lang_hdr; + +/** Create Accept-Language header. */ +#define pjsip_accept_lang_hdr_create pjsip_generic_string_hdr_create + +/** Alert-Info header. */ +typedef pjsip_generic_string_hdr pjsip_alert_info_hdr; + +/** Create Alert-Info header. */ +#define pjsip_alert_info_hdr_create pjsip_generic_string_hdr_create + +/** Authentication-Info header. */ +typedef pjsip_generic_string_hdr pjsip_auth_info_hdr; + +/** Create Authentication-Info header. */ +#define pjsip_auth_info_hdr_create pjsip_generic_string_hdr_create + +/** Call-Info header. */ +typedef pjsip_generic_string_hdr pjsip_call_info_hdr; + +/** Create Call-Info header. */ +#define pjsip_call_info_hdr_create pjsip_generic_string_hdr_create + +/** Content-Disposition header. */ +typedef pjsip_generic_string_hdr pjsip_content_disposition_hdr; + +/** Create Content-Disposition header. */ +#define pjsip_content_disposition_hdr_create pjsip_generic_string_hdr_create + +/** Content-Encoding header. */ +typedef pjsip_generic_string_hdr pjsip_content_encoding_hdr; + +/** Create Content-Encoding header. */ +#define pjsip_content_encoding_hdr_create pjsip_generic_string_hdr_create + +/** Content-Language header. */ +typedef pjsip_generic_string_hdr pjsip_content_lang_hdr; + +/** Create Content-Language header. */ +#define pjsip_content_lang_hdr_create pjsip_generic_string_hdr_create + +/** Date header. */ +typedef pjsip_generic_string_hdr pjsip_date_hdr; + +/** Create Date header. */ +#define pjsip_date_hdr_create pjsip_generic_string_hdr_create + +/** Error-Info header. */ +typedef pjsip_generic_string_hdr pjsip_err_info_hdr; + +/** Create Error-Info header. */ +#define pjsip_err_info_hdr_create pjsip_generic_string_hdr_create + +/** In-Reply-To header. */ +typedef pjsip_generic_string_hdr pjsip_in_reply_to_hdr; + +/** Create In-Reply-To header. */ +#define pjsip_in_reply_to_hdr_create pjsip_generic_string_hdr_create + +/** MIME-Version header. */ +typedef pjsip_generic_string_hdr pjsip_mime_version_hdr; + +/** Create MIME-Version header. */ +#define pjsip_mime_version_hdr_create pjsip_generic_string_hdr_create + +/** Organization header. */ +typedef pjsip_generic_string_hdr pjsip_organization_hdr; + +/** Create Organization header. */ +#define pjsip_organization_hdr_create pjsip_genric_string_hdr_create + +/** Priority header. */ +typedef pjsip_generic_string_hdr pjsip_priority_hdr; + +/** Create Priority header. */ +#define pjsip_priority_hdr_create pjsip_generic_string_hdr_create + +/** Proxy-Require header. */ +typedef pjsip_generic_string_hdr pjsip_proxy_require_hdr; + +/** Reply-To header. */ +typedef pjsip_generic_string_hdr pjsip_reply_to_hdr; + +/** Create Reply-To header. */ +#define pjsip_reply_to_hdr_create pjsip_generic_string_hdr_create + +/** Server header. */ +typedef pjsip_generic_string_hdr pjsip_server_hdr; + +/** Create Server header. */ +#define pjsip_server_hdr_create pjsip_generic_string_hdr_create + +/** Subject header. */ +typedef pjsip_generic_string_hdr pjsip_subject_hdr; + +/** Create Subject header. */ +#define pjsip_subject_hdr_create pjsip_generic_string_hdr_create + +/** Timestamp header. */ +typedef pjsip_generic_string_hdr pjsip_timestamp_hdr; + +/** Create Timestamp header. */ +#define pjsip_timestamp_hdr_create pjsip_generic_string_hdr_create + +/** User-Agent header. */ +typedef pjsip_generic_string_hdr pjsip_user_agent_hdr; + +/** Create User-Agent header. */ +#define pjsip_user_agent_hdr_create pjsip_generic_string_hdr_create + +/** Warning header. */ +typedef pjsip_generic_string_hdr pjsip_warning_hdr; + +/** Create Warning header. */ +#define pjsip_warning_hdr_create pjsip_generic_string_hdr_create + +/** + * @} + */ + +/** + * @} // PJSIP_MSG + */ + +/* + * Include inline definitions. + */ +#if PJ_FUNCTIONS_ARE_INLINED +# include <pjsip/sip_msg_i.h> +#endif + + +PJ_END_DECL + +#endif /* __PJSIP_SIP_MSG_H__ */ + diff --git a/pjsip/include/pjsip/sip_msg_i.h b/pjsip/include/pjsip/sip_msg_i.h index 4a545ca8..c6c87b9a 100644 --- a/pjsip/include/pjsip/sip_msg_i.h +++ b/pjsip/include/pjsip/sip_msg_i.h @@ -1,29 +1,29 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
-PJ_IDEF(void) pjsip_msg_add_hdr( pjsip_msg *msg, pjsip_hdr *hdr )
-{
- pj_list_insert_before(&msg->hdr, hdr);
-}
-
-PJ_IDEF(void) pjsip_msg_insert_first_hdr( pjsip_msg *msg, pjsip_hdr *hdr )
-{
- pj_list_insert_after(&msg->hdr, hdr);
-}
-
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ + +PJ_IDEF(void) pjsip_msg_add_hdr( pjsip_msg *msg, pjsip_hdr *hdr ) +{ + pj_list_insert_before(&msg->hdr, hdr); +} + +PJ_IDEF(void) pjsip_msg_insert_first_hdr( pjsip_msg *msg, pjsip_hdr *hdr ) +{ + pj_list_insert_after(&msg->hdr, hdr); +} + diff --git a/pjsip/include/pjsip/sip_parser.h b/pjsip/include/pjsip/sip_parser.h index 6c30e837..2b4e6c14 100644 --- a/pjsip/include/pjsip/sip_parser.h +++ b/pjsip/include/pjsip/sip_parser.h @@ -1,353 +1,353 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIP_PARSER_H__
-#define __PJSIP_SIP_PARSER_H__
-
-/**
- * @file sip_parser.h
- * @brief SIP Message Parser
- */
-
-#include <pjsip/sip_types.h>
-#include <pjlib-util/scanner.h>
-#include <pj/list.h>
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJSIP_PARSER SIP Message Parser
- * @ingroup PJSIP
- * @{
- */
-
-/**
- * URI Parsing options.
- */
-enum
-{
- /** If this option is specified, function #pjsip_parse_uri will return
- * the URI object as pjsip_name_addr instead of the corresponding
- * URI object.
- */
- PJSIP_PARSE_URI_AS_NAMEADDR = 1,
-
- /** If this option is specified, function #pjsip_parse_uri and other
- * internal functions that this function calls will parse URI according
- * to convention for parsing From/To header. For example, when the URI
- * is not enclosed in brackets ("<" and ">"), all parameters will not
- * be stored to the URI (it will be stored to the header).
- */
- PJSIP_PARSE_URI_IN_FROM_TO_HDR = 2,
-};
-
-/**
- * Parser syntax error exception value.
- */
-#define PJSIP_SYN_ERR_EXCEPTION 1
-
-/**
- * This structure is used to get error reporting from parser.
- */
-typedef struct pjsip_parser_err_report
-{
- PJ_DECL_LIST_MEMBER(struct pjsip_parser_err_report);
- int exception_code; /**< Error exception (e.g. PJSIP_SYN_ERR_EXCEPTION) */
- int line; /**< Line number. */
- int col; /**< Column number. */
- pj_str_t hname; /**< Header name, if any. */
-} pjsip_parser_err_report;
-
-
-/**
- * Parsing context, the default argument for parsing functions.
- */
-typedef struct pjsip_parse_ctx
-{
- pj_scanner *scanner; /**< The scanner. */
- pj_pool_t *pool; /**< The pool. */
- pjsip_rx_data *rdata; /**< Optional rdata. */
-} pjsip_parse_ctx;
-
-
-/**
- * Type of function to parse header. The parsing function must follow these
- * specification:
- * - It must not modify the input text.
- * - The hname and HCOLON has been parsed prior to invoking the handler.
- * - It returns the header instance on success.
- * - For error reporting, it must throw PJSIP_SYN_ERR_EXCEPTION exception
- * instead of just returning NULL.
- * When exception is thrown, the return value is ignored.
- * - It must read the header separator after finished reading the header
- * body. The separator types are described below, and if they don't exist,
- * exception must be thrown. Header separator can be a:
- * - newline, such as when the header is part of a SIP message.
- * - ampersand, such as when the header is part of an URI.
- * - for the last header, these separator is optional since parsing
- * can be terminated when seeing EOF.
- */
-typedef pjsip_hdr* (pjsip_parse_hdr_func)(pjsip_parse_ctx *context);
-
-/**
- * Type of function to parse URI scheme.
- * Most of the specification of header parser handler (pjsip_parse_hdr_func)
- * also applies here (except the separator part).
- */
-typedef void* (pjsip_parse_uri_func)(pj_scanner *scanner, pj_pool_t *pool);
-
-/**
- * Register header parser handler. The parser handler MUST follow the
- * specification of header parser handler function. New registration
- * overwrites previous registration with the same name.
- *
- * @param hname The header name.
- * @param hshortname The short header name or NULL.
- * @param fptr The pointer to function to parser the header.
- *
- * @return PJ_SUCCESS if success, or the appropriate error code.
- */
-PJ_DECL(pj_status_t) pjsip_register_hdr_parser( const char *hname,
- const char *hshortname,
- pjsip_parse_hdr_func *fptr);
-
-/**
- * Unregister previously registered header parser handler.
- * All the arguments MUST exactly equal to the value specified upon
- * registration of the handler.
- *
- * @param hname The header name registered.
- * @param hshortname The short header name registered, or NULL.
- *
- * @return zero if unregistration was successfull.
- */
-PJ_DECL(pj_status_t) pjsip_unregister_hdr_parser( const char *hname,
- const char *hshortname,
- pjsip_parse_hdr_func *fptr);
-
-/**
- * Register URI scheme parser handler.
- *
- * @param scheme The URI scheme registered.
- * @param func The URI parser function.
- *
- * @return zero on success.
- */
-PJ_DECL(pj_status_t) pjsip_register_uri_parser( const char *scheme,
- pjsip_parse_uri_func *func);
-
-/**
- * Unregister URI scheme parser handler.
- * All the arguments MUST exactly equal to the value specified upon
- * registration of the handler.
- *
- * @param scheme The URI scheme as registered previously.
- * @param func The function handler as registered previously.
- *
- * @return zero if the registration was successfull.
- */
-PJ_DECL(pj_status_t) pjsip_unregister_uri_parser( const char *scheme,
- pjsip_parse_uri_func *func);
-
-/**
- * Parse an URI in the input and return the correct instance of URI.
- *
- * @param pool The pool to get memory allocations.
- * @param buf The input buffer, which size must be at least (size+1)
- * because the function will temporarily put NULL
- * termination at the end of the buffer during parsing.
- * @param size The length of the string (not counting NULL terminator).
- * @param options If no options are given (value is zero), the object
- * returned is dependent on the syntax of the URI,
- * eg. basic SIP URL, TEL URL, or name address.
- * If option PJSIP_PARSE_URI_AS_NAMEADDR is given,
- * then the returned object is always name address object,
- * with the relevant URI object contained in the name
- * address object.
- * @return The URI or NULL when failed. No exception is thrown by
- * this function (or any public parser functions).
- */
-PJ_DECL(pjsip_uri*) pjsip_parse_uri( pj_pool_t *pool,
- char *buf, pj_size_t size,
- unsigned option);
-
-/**
- * Parse a packet buffer and build a full SIP message from the packet. This
- * function parses all parts of the message, including request/status line,
- * all headers, and the message body. The message body however is only
- * treated as a text block, ie. the function will not try to parse the content
- * of the body.
- *
- * @param pool The pool to allocate memory.
- * @param buf The input buffer, which size must be at least (size+1)
- * because the function will temporarily put NULL
- * termination at the end of the buffer during parsing.
- * @param size The length of the string (not counting NULL terminator).
- * @param err_list If this parameter is not NULL, then the parser will
- * put error messages during parsing in this list.
- *
- * @return The message or NULL when failed. No exception is thrown
- * by this function (or any public parser functions).
- */
-PJ_DECL(pjsip_msg *) pjsip_parse_msg( pj_pool_t *pool,
- char *buf, pj_size_t size,
- pjsip_parser_err_report *err_list);
-
-
-/**
- * Parse a packet buffer and build a rdata. The resulting message will be
- * stored in \c msg field in the \c rdata. This behaves pretty much like
- * #pjsip_parse_msg(), except that it will also initialize the header fields
- * in the \c rdata.
- *
- * This function is normally called by the transport layer.
- *
- * @param buf The input buffer
- * @param buf The input buffer, which size must be at least (size+1)
- * because the function will temporarily put NULL
- * termination at the end of the buffer during parsing.
- * @param size The length of the string (not counting NULL terminator).
- * @param rdata The receive data buffer to store the message and
- * its elements.
- *
- * @return The message inside the rdata if successfull, or NULL.
- */
-PJ_DECL(pjsip_msg *) pjsip_parse_rdata( char *buf, pj_size_t size,
- pjsip_rx_data *rdata );
-
-/**
- * Check incoming packet to see if a (probably) valid SIP message has been
- * received.
- *
- * @param buf The input buffer, which must be NULL terminated.
- * @param size The buffer size.
- * @param msg_size [out] If message is valid, this parameter will contain
- * the size of the SIP message (including body, if any).
- *
- * @return PJ_SUCCESS if a message is found, or an error code.
- */
-PJ_DECL(pj_status_t) pjsip_find_msg(const char *buf,
- pj_size_t size,
- pj_bool_t is_datagram,
- pj_size_t *msg_size);
-
-/**
- * Parse the content of a header and return the header instance.
- * This function parses the content of a header (ie. part after colon) according
- * to the expected name, and will return the correct instance of header.
- *
- * @param pool Pool to allocate memory for the header.
- * @param hname Header name which is used to find the correct function
- * to parse the header.
- * @param line Header content, which size must be at least size+1.
- * @param size The length of the string (not counting NULL terminator,
- * if any).
- * @param parsed_len If the value is not NULL, then upon return the function
- * will fill the pointer with the length of the string
- * that has been parsed. This is usefull for two purposes,
- * one is when the string may contain more than one header
- * lines, and two when an error happen the value can
- * pinpoint the location of the error in the buffer.
- *
- * @return The instance of the header if parsing was successfull,
- * or otherwise a NULL pointer will be returned.
- */
-PJ_DECL(void*) pjsip_parse_hdr( pj_pool_t *pool, const pj_str_t *hname,
- char *line, pj_size_t size,
- int *parsed_len);
-
-/**
- * Parse header line(s). Multiple headers can be parsed by this function.
- * When there are multiple headers, the headers MUST be separated by either
- * a newline (as in SIP message) or ampersand mark (as in URI). This separator
- * however is optional for the last header.
- *
- * @param pool the pool.
- * @param buf the input text to parse.
- * @param size the text length.
- * @param hlist the header list to store the parsed headers. This list must
- * have been initialized before calling this function.
- * @return zero if successfull, or -1 if error is encountered. Upon error,
- * the \a hlist argument MAY contain successfully parsed headers.
- */
-PJ_DECL(pj_status_t) pjsip_parse_headers( pj_pool_t *pool,
- char *input, pj_size_t size,
- pj_list *hlist );
-
-
-/*
- * Various specification used in parsing, exported here as extern for other
- * parsers.
- */
-extern pj_cis_t
- pjsip_HOST_SPEC, /**< For scanning host part. */
- pjsip_DIGIT_SPEC, /**< Decimal digits */
- pjsip_ALPHA_SPEC, /**< Alpha (A-Z, a-z) */
- pjsip_ALNUM_SPEC, /**< Decimal + Alpha. */
- pjsip_TOKEN_SPEC, /**< Token. */
- pjsip_HEX_SPEC, /**< Hexadecimal digits. */
- pjsip_PARAM_CHAR_SPEC, /**< For scanning pname (or pvalue when it's
- not quoted.) */
- pjsip_HDR_CHAR_SPEC, /**< Chars in hname/havalue in URL. */
- pjsip_PROBE_USER_HOST_SPEC, /**< Hostname characters. */
- pjsip_PASSWD_SPEC, /**< Password. */
- pjsip_USER_SPEC, /**< User */
- pjsip_NEWLINE_OR_EOF_SPEC, /**< For eating up header.*/
- pjsip_DISPLAY_SCAN_SPEC; /**< Used when searching for display name. */
-
-/*
- * Various string constants.
- */
-extern const pj_str_t pjsip_USER_STR,
- pjsip_METHOD_STR,
- pjsip_TRANSPORT_STR,
- pjsip_MADDR_STR,
- pjsip_LR_STR,
- pjsip_SIP_STR,
- pjsip_SIPS_STR,
- pjsip_TEL_STR,
- pjsip_BRANCH_STR,
- pjsip_TTL_STR,
- pjsip_PNAME_STR,
- pjsip_Q_STR,
- pjsip_EXPIRES_STR,
- pjsip_TAG_STR;
-
-/*
- * Parser utilities.
- */
-enum
-{
- PJSIP_PARSE_REMOVE_QUOTE = 1,
-};
-
-void pjsip_parse_param_imp( pj_scanner *scanner,
- pj_str_t *pname, pj_str_t *pvalue,
- unsigned opt);
-void pjsip_concat_param_imp( pj_str_t *param, pj_pool_t *pool,
- const pj_str_t *pname, const pj_str_t *pvalue, int sepchar);
-void pjsip_parse_end_hdr_imp ( pj_scanner *scanner );
-
-/**
- * @}
- */
-
-PJ_END_DECL
-
-#endif /* __PJSIP_SIP_PARSER_H__ */
-
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIP_PARSER_H__ +#define __PJSIP_SIP_PARSER_H__ + +/** + * @file sip_parser.h + * @brief SIP Message Parser + */ + +#include <pjsip/sip_types.h> +#include <pjlib-util/scanner.h> +#include <pj/list.h> + +PJ_BEGIN_DECL + +/** + * @defgroup PJSIP_PARSER SIP Message Parser + * @ingroup PJSIP + * @{ + */ + +/** + * URI Parsing options. + */ +enum +{ + /** If this option is specified, function #pjsip_parse_uri will return + * the URI object as pjsip_name_addr instead of the corresponding + * URI object. + */ + PJSIP_PARSE_URI_AS_NAMEADDR = 1, + + /** If this option is specified, function #pjsip_parse_uri and other + * internal functions that this function calls will parse URI according + * to convention for parsing From/To header. For example, when the URI + * is not enclosed in brackets ("<" and ">"), all parameters will not + * be stored to the URI (it will be stored to the header). + */ + PJSIP_PARSE_URI_IN_FROM_TO_HDR = 2, +}; + +/** + * Parser syntax error exception value. + */ +#define PJSIP_SYN_ERR_EXCEPTION 1 + +/** + * This structure is used to get error reporting from parser. + */ +typedef struct pjsip_parser_err_report +{ + PJ_DECL_LIST_MEMBER(struct pjsip_parser_err_report); + int exception_code; /**< Error exception (e.g. PJSIP_SYN_ERR_EXCEPTION) */ + int line; /**< Line number. */ + int col; /**< Column number. */ + pj_str_t hname; /**< Header name, if any. */ +} pjsip_parser_err_report; + + +/** + * Parsing context, the default argument for parsing functions. + */ +typedef struct pjsip_parse_ctx +{ + pj_scanner *scanner; /**< The scanner. */ + pj_pool_t *pool; /**< The pool. */ + pjsip_rx_data *rdata; /**< Optional rdata. */ +} pjsip_parse_ctx; + + +/** + * Type of function to parse header. The parsing function must follow these + * specification: + * - It must not modify the input text. + * - The hname and HCOLON has been parsed prior to invoking the handler. + * - It returns the header instance on success. + * - For error reporting, it must throw PJSIP_SYN_ERR_EXCEPTION exception + * instead of just returning NULL. + * When exception is thrown, the return value is ignored. + * - It must read the header separator after finished reading the header + * body. The separator types are described below, and if they don't exist, + * exception must be thrown. Header separator can be a: + * - newline, such as when the header is part of a SIP message. + * - ampersand, such as when the header is part of an URI. + * - for the last header, these separator is optional since parsing + * can be terminated when seeing EOF. + */ +typedef pjsip_hdr* (pjsip_parse_hdr_func)(pjsip_parse_ctx *context); + +/** + * Type of function to parse URI scheme. + * Most of the specification of header parser handler (pjsip_parse_hdr_func) + * also applies here (except the separator part). + */ +typedef void* (pjsip_parse_uri_func)(pj_scanner *scanner, pj_pool_t *pool); + +/** + * Register header parser handler. The parser handler MUST follow the + * specification of header parser handler function. New registration + * overwrites previous registration with the same name. + * + * @param hname The header name. + * @param hshortname The short header name or NULL. + * @param fptr The pointer to function to parser the header. + * + * @return PJ_SUCCESS if success, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsip_register_hdr_parser( const char *hname, + const char *hshortname, + pjsip_parse_hdr_func *fptr); + +/** + * Unregister previously registered header parser handler. + * All the arguments MUST exactly equal to the value specified upon + * registration of the handler. + * + * @param hname The header name registered. + * @param hshortname The short header name registered, or NULL. + * + * @return zero if unregistration was successfull. + */ +PJ_DECL(pj_status_t) pjsip_unregister_hdr_parser( const char *hname, + const char *hshortname, + pjsip_parse_hdr_func *fptr); + +/** + * Register URI scheme parser handler. + * + * @param scheme The URI scheme registered. + * @param func The URI parser function. + * + * @return zero on success. + */ +PJ_DECL(pj_status_t) pjsip_register_uri_parser( const char *scheme, + pjsip_parse_uri_func *func); + +/** + * Unregister URI scheme parser handler. + * All the arguments MUST exactly equal to the value specified upon + * registration of the handler. + * + * @param scheme The URI scheme as registered previously. + * @param func The function handler as registered previously. + * + * @return zero if the registration was successfull. + */ +PJ_DECL(pj_status_t) pjsip_unregister_uri_parser( const char *scheme, + pjsip_parse_uri_func *func); + +/** + * Parse an URI in the input and return the correct instance of URI. + * + * @param pool The pool to get memory allocations. + * @param buf The input buffer, which size must be at least (size+1) + * because the function will temporarily put NULL + * termination at the end of the buffer during parsing. + * @param size The length of the string (not counting NULL terminator). + * @param options If no options are given (value is zero), the object + * returned is dependent on the syntax of the URI, + * eg. basic SIP URL, TEL URL, or name address. + * If option PJSIP_PARSE_URI_AS_NAMEADDR is given, + * then the returned object is always name address object, + * with the relevant URI object contained in the name + * address object. + * @return The URI or NULL when failed. No exception is thrown by + * this function (or any public parser functions). + */ +PJ_DECL(pjsip_uri*) pjsip_parse_uri( pj_pool_t *pool, + char *buf, pj_size_t size, + unsigned option); + +/** + * Parse a packet buffer and build a full SIP message from the packet. This + * function parses all parts of the message, including request/status line, + * all headers, and the message body. The message body however is only + * treated as a text block, ie. the function will not try to parse the content + * of the body. + * + * @param pool The pool to allocate memory. + * @param buf The input buffer, which size must be at least (size+1) + * because the function will temporarily put NULL + * termination at the end of the buffer during parsing. + * @param size The length of the string (not counting NULL terminator). + * @param err_list If this parameter is not NULL, then the parser will + * put error messages during parsing in this list. + * + * @return The message or NULL when failed. No exception is thrown + * by this function (or any public parser functions). + */ +PJ_DECL(pjsip_msg *) pjsip_parse_msg( pj_pool_t *pool, + char *buf, pj_size_t size, + pjsip_parser_err_report *err_list); + + +/** + * Parse a packet buffer and build a rdata. The resulting message will be + * stored in \c msg field in the \c rdata. This behaves pretty much like + * #pjsip_parse_msg(), except that it will also initialize the header fields + * in the \c rdata. + * + * This function is normally called by the transport layer. + * + * @param buf The input buffer + * @param buf The input buffer, which size must be at least (size+1) + * because the function will temporarily put NULL + * termination at the end of the buffer during parsing. + * @param size The length of the string (not counting NULL terminator). + * @param rdata The receive data buffer to store the message and + * its elements. + * + * @return The message inside the rdata if successfull, or NULL. + */ +PJ_DECL(pjsip_msg *) pjsip_parse_rdata( char *buf, pj_size_t size, + pjsip_rx_data *rdata ); + +/** + * Check incoming packet to see if a (probably) valid SIP message has been + * received. + * + * @param buf The input buffer, which must be NULL terminated. + * @param size The buffer size. + * @param msg_size [out] If message is valid, this parameter will contain + * the size of the SIP message (including body, if any). + * + * @return PJ_SUCCESS if a message is found, or an error code. + */ +PJ_DECL(pj_status_t) pjsip_find_msg(const char *buf, + pj_size_t size, + pj_bool_t is_datagram, + pj_size_t *msg_size); + +/** + * Parse the content of a header and return the header instance. + * This function parses the content of a header (ie. part after colon) according + * to the expected name, and will return the correct instance of header. + * + * @param pool Pool to allocate memory for the header. + * @param hname Header name which is used to find the correct function + * to parse the header. + * @param line Header content, which size must be at least size+1. + * @param size The length of the string (not counting NULL terminator, + * if any). + * @param parsed_len If the value is not NULL, then upon return the function + * will fill the pointer with the length of the string + * that has been parsed. This is usefull for two purposes, + * one is when the string may contain more than one header + * lines, and two when an error happen the value can + * pinpoint the location of the error in the buffer. + * + * @return The instance of the header if parsing was successfull, + * or otherwise a NULL pointer will be returned. + */ +PJ_DECL(void*) pjsip_parse_hdr( pj_pool_t *pool, const pj_str_t *hname, + char *line, pj_size_t size, + int *parsed_len); + +/** + * Parse header line(s). Multiple headers can be parsed by this function. + * When there are multiple headers, the headers MUST be separated by either + * a newline (as in SIP message) or ampersand mark (as in URI). This separator + * however is optional for the last header. + * + * @param pool the pool. + * @param buf the input text to parse. + * @param size the text length. + * @param hlist the header list to store the parsed headers. This list must + * have been initialized before calling this function. + * @return zero if successfull, or -1 if error is encountered. Upon error, + * the \a hlist argument MAY contain successfully parsed headers. + */ +PJ_DECL(pj_status_t) pjsip_parse_headers( pj_pool_t *pool, + char *input, pj_size_t size, + pj_list *hlist ); + + +/* + * Various specification used in parsing, exported here as extern for other + * parsers. + */ +extern pj_cis_t + pjsip_HOST_SPEC, /**< For scanning host part. */ + pjsip_DIGIT_SPEC, /**< Decimal digits */ + pjsip_ALPHA_SPEC, /**< Alpha (A-Z, a-z) */ + pjsip_ALNUM_SPEC, /**< Decimal + Alpha. */ + pjsip_TOKEN_SPEC, /**< Token. */ + pjsip_HEX_SPEC, /**< Hexadecimal digits. */ + pjsip_PARAM_CHAR_SPEC, /**< For scanning pname (or pvalue when it's + not quoted.) */ + pjsip_HDR_CHAR_SPEC, /**< Chars in hname/havalue in URL. */ + pjsip_PROBE_USER_HOST_SPEC, /**< Hostname characters. */ + pjsip_PASSWD_SPEC, /**< Password. */ + pjsip_USER_SPEC, /**< User */ + pjsip_NEWLINE_OR_EOF_SPEC, /**< For eating up header.*/ + pjsip_DISPLAY_SCAN_SPEC; /**< Used when searching for display name. */ + +/* + * Various string constants. + */ +extern const pj_str_t pjsip_USER_STR, + pjsip_METHOD_STR, + pjsip_TRANSPORT_STR, + pjsip_MADDR_STR, + pjsip_LR_STR, + pjsip_SIP_STR, + pjsip_SIPS_STR, + pjsip_TEL_STR, + pjsip_BRANCH_STR, + pjsip_TTL_STR, + pjsip_PNAME_STR, + pjsip_Q_STR, + pjsip_EXPIRES_STR, + pjsip_TAG_STR; + +/* + * Parser utilities. + */ +enum +{ + PJSIP_PARSE_REMOVE_QUOTE = 1, +}; + +void pjsip_parse_param_imp( pj_scanner *scanner, pj_pool_t *pool, + pj_str_t *pname, pj_str_t *pvalue, + unsigned opt); +void pjsip_concat_param_imp( pj_str_t *param, pj_pool_t *pool, + const pj_str_t *pname, const pj_str_t *pvalue, int sepchar); +void pjsip_parse_end_hdr_imp ( pj_scanner *scanner ); + +/** + * @} + */ + +PJ_END_DECL + +#endif /* __PJSIP_SIP_PARSER_H__ */ + diff --git a/pjsip/include/pjsip/sip_private.h b/pjsip/include/pjsip/sip_private.h index 1c14e607..80417906 100644 --- a/pjsip/include/pjsip/sip_private.h +++ b/pjsip/include/pjsip/sip_private.h @@ -1,46 +1,46 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIP_PRIVATE_H__
-#define __PJSIP_SIP_PRIVATE_H__
-
-/**
- * @file sip_private.h
- * @brief Private structures and functions for PJSIP Library.
- */
-
-#include <pjsip/sip_types.h>
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJSIP_PRIVATE Private structures and functions (PJSIP internals)
- * @ingroup PJSIP
- * @{
- */
-
-
-
-/**
- * @}
- */
-
-PJ_END_DECL
-
-#endif /* __PJSIP_PRIVATE_I_H__ */
-
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIP_PRIVATE_H__ +#define __PJSIP_SIP_PRIVATE_H__ + +/** + * @file sip_private.h + * @brief Private structures and functions for PJSIP Library. + */ + +#include <pjsip/sip_types.h> + +PJ_BEGIN_DECL + +/** + * @defgroup PJSIP_PRIVATE Private structures and functions (PJSIP internals) + * @ingroup PJSIP + * @{ + */ + + + +/** + * @} + */ + +PJ_END_DECL + +#endif /* __PJSIP_PRIVATE_I_H__ */ + diff --git a/pjsip/include/pjsip/sip_resolve.h b/pjsip/include/pjsip/sip_resolve.h index efc54ace..673de2a7 100644 --- a/pjsip/include/pjsip/sip_resolve.h +++ b/pjsip/include/pjsip/sip_resolve.h @@ -1,120 +1,120 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIP_RESOLVE_H__
-#define __PJSIP_SIP_RESOLVE_H__
-
-/**
- * @file sip_resolve.h
- * @brief
- * This module contains the mechanism to resolve server address as specified by
- * RFC 3263 - Locating SIP Servers
- */
-
-#include <pjsip/sip_types.h>
-#include <pj/sock.h>
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJSIP_RESOLVE SIP Server Resolver
- * @ingroup PJSIP
- * @{
- */
-
-/**
- * Maximum number of addresses returned by the resolver.
- */
-#define PJSIP_MAX_RESOLVED_ADDRESSES 8
-
-typedef struct pjsip_server_addresses pjsip_server_addresses;
-
-/**
- * The server addresses returned by the resolver.
- */
-struct pjsip_server_addresses
-{
- /** Number of address records. */
- unsigned count;
-
- /** Address records. */
- struct
- {
- /** Preferable transport to be used to contact this address. */
- pjsip_transport_type_e type;
-
- /** The server's address. */
- pj_sockaddr_in addr;
-
- } entry[PJSIP_MAX_RESOLVED_ADDRESSES];
-
-};
-
-/**
- * The type of callback function to be called when resolver finishes the job.
- *
- * @param status The status of the operation, which is zero on success.
- * @param token The token that was associated with the job when application
- * call the resolve function.
- * @param addr The addresses resolved by the operation.
- */
-typedef void pjsip_resolver_callback(pj_status_t status,
- void *token,
- const struct pjsip_server_addresses *addr);
-
-/**
- * Create resolver engine.
- *
- * @param pool The Pool.
- * @return The resolver engine.
- */
-PJ_DECL(pjsip_resolver_t*) pjsip_resolver_create(pj_pool_t *pool);
-
-/**
- * Destroy resolver engine.
- *
- * @param resolver The resolver.
- */
-PJ_DECL(void) pjsip_resolver_destroy(pjsip_resolver_t *resolver);
-
-/**
- * Asynchronously resolve a SIP target host or domain according to rule
- * specified in RFC 3263 (Locating SIP Servers). When the resolving operation
- * has completed, the callback will be called.
- *
- * Note: at the moment we don't have implementation of RFC 3263 yet!
- *
- * @param resolver The resolver engine.
- * @param pool The pool to allocate resolver job.
- * @param target The target specification to be resolved.
- * @param token A user defined token to be passed back to callback function.
- * @param cb The callback function.
- */
-PJ_DECL(void) pjsip_resolve( pjsip_resolver_t *resolver,
- pj_pool_t *pool,
- pjsip_host_port *target,
- void *token,
- pjsip_resolver_callback *cb);
-
-/**
- * @}
- */
-
-PJ_END_DECL
-
-#endif /* __PJSIP_SIP_RESOLVE_H__ */
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIP_RESOLVE_H__ +#define __PJSIP_SIP_RESOLVE_H__ + +/** + * @file sip_resolve.h + * @brief + * This module contains the mechanism to resolve server address as specified by + * RFC 3263 - Locating SIP Servers + */ + +#include <pjsip/sip_types.h> +#include <pj/sock.h> + +PJ_BEGIN_DECL + +/** + * @defgroup PJSIP_RESOLVE SIP Server Resolver + * @ingroup PJSIP + * @{ + */ + +/** + * Maximum number of addresses returned by the resolver. + */ +#define PJSIP_MAX_RESOLVED_ADDRESSES 8 + +typedef struct pjsip_server_addresses pjsip_server_addresses; + +/** + * The server addresses returned by the resolver. + */ +struct pjsip_server_addresses +{ + /** Number of address records. */ + unsigned count; + + /** Address records. */ + struct + { + /** Preferable transport to be used to contact this address. */ + pjsip_transport_type_e type; + + /** The server's address. */ + pj_sockaddr_in addr; + + } entry[PJSIP_MAX_RESOLVED_ADDRESSES]; + +}; + +/** + * The type of callback function to be called when resolver finishes the job. + * + * @param status The status of the operation, which is zero on success. + * @param token The token that was associated with the job when application + * call the resolve function. + * @param addr The addresses resolved by the operation. + */ +typedef void pjsip_resolver_callback(pj_status_t status, + void *token, + const struct pjsip_server_addresses *addr); + +/** + * Create resolver engine. + * + * @param pool The Pool. + * @return The resolver engine. + */ +PJ_DECL(pjsip_resolver_t*) pjsip_resolver_create(pj_pool_t *pool); + +/** + * Destroy resolver engine. + * + * @param resolver The resolver. + */ +PJ_DECL(void) pjsip_resolver_destroy(pjsip_resolver_t *resolver); + +/** + * Asynchronously resolve a SIP target host or domain according to rule + * specified in RFC 3263 (Locating SIP Servers). When the resolving operation + * has completed, the callback will be called. + * + * Note: at the moment we don't have implementation of RFC 3263 yet! + * + * @param resolver The resolver engine. + * @param pool The pool to allocate resolver job. + * @param target The target specification to be resolved. + * @param token A user defined token to be passed back to callback function. + * @param cb The callback function. + */ +PJ_DECL(void) pjsip_resolve( pjsip_resolver_t *resolver, + pj_pool_t *pool, + pjsip_host_port *target, + void *token, + pjsip_resolver_callback *cb); + +/** + * @} + */ + +PJ_END_DECL + +#endif /* __PJSIP_SIP_RESOLVE_H__ */ diff --git a/pjsip/include/pjsip/sip_transaction.h b/pjsip/include/pjsip/sip_transaction.h index e7edceef..e95c66b1 100644 --- a/pjsip/include/pjsip/sip_transaction.h +++ b/pjsip/include/pjsip/sip_transaction.h @@ -1,271 +1,271 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIP_TRANSACTION_H__
-#define __PJSIP_SIP_TRANSACTION_H__
-
-/**
- * @file sip_transaction.h
- * @brief SIP Transaction
- */
-
-#include <pjsip/sip_msg.h>
-#include <pjsip/sip_resolve.h>
-#include <pj/timer.h>
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJSIP_TRANSACT SIP Transaction
- * @ingroup PJSIP
- * @{
- */
-
-/* Forward decl. */
-struct pjsip_transaction;
-
-
-/**
- * Transaction state.
- */
-typedef enum pjsip_tsx_state_e
-{
- PJSIP_TSX_STATE_NULL,
- PJSIP_TSX_STATE_CALLING,
- PJSIP_TSX_STATE_TRYING,
- PJSIP_TSX_STATE_PROCEEDING,
- PJSIP_TSX_STATE_COMPLETED,
- PJSIP_TSX_STATE_CONFIRMED,
- PJSIP_TSX_STATE_TERMINATED,
- PJSIP_TSX_STATE_DESTROYED,
- PJSIP_TSX_STATE_MAX,
-} pjsip_tsx_state_e;
-
-
-/**
- * State of the transport in the transaction.
- * The transport is progressing independently of the transaction.
- */
-typedef enum pjsip_tsx_transport_state_e
-{
- PJSIP_TSX_TRANSPORT_STATE_NULL,
- PJSIP_TSX_TRANSPORT_STATE_RESOLVING,
- PJSIP_TSX_TRANSPORT_STATE_CONNECTING,
- PJSIP_TSX_TRANSPORT_STATE_FINAL,
-} pjsip_tsx_transport_state_e;
-
-
-/**
- * Transaction state.
- */
-struct pjsip_transaction
-{
- /*
- * Administrivia
- */
- pj_pool_t *pool; /**< Pool owned by the tsx. */
- pjsip_endpoint *endpt; /**< Endpoint instance. */
- pj_mutex_t *mutex; /**< Mutex for this tsx. */
- char obj_name[PJ_MAX_OBJ_NAME]; /**< Tsx name. */
- int tracing; /**< Tracing enabled? */
-
- /*
- * Transaction identification.
- */
- pjsip_role_e role; /**< Role (UAS or UAC) */
- pjsip_method method; /**< The method. */
- int cseq; /**< The CSeq */
- pj_str_t transaction_key;/**< hash table key. */
- pj_str_t branch; /**< The branch Id. */
-
- /*
- * State and status.
- */
- int status_code; /**< Last status code seen. */
- pjsip_tsx_state_e state; /**< State. */
- int handle_ack; /**< Should we handle ACK? */
-
- /** Handler according to current state. */
- pj_status_t (*state_handler)(struct pjsip_transaction *, pjsip_event *);
-
- /*
- * Transport.
- */
- pjsip_tsx_transport_state_e transport_state;/**< Transport's state. */
- pjsip_host_port dest_name; /**< Destination address. */
- pjsip_server_addresses remote_addr; /**< Addresses resolved. */
- int current_addr; /**< Address currently used. */
-
- pjsip_transport *transport; /**< Transport to use. */
-
- /*
- * Messages and timer.
- */
- pjsip_tx_data *last_tx; /**< Msg kept for retrans. */
- int has_unsent_msg; /**< Non-zero if tsx need to
- transmit msg once resolver
- completes. */
- int retransmit_count;/**< Retransmission count. */
- pj_timer_entry retransmit_timer;/**< Retransmit timer. */
- pj_timer_entry timeout_timer; /**< Timeout timer. */
-
- /** Module specific data. */
- void *module_data[PJSIP_MAX_MODULE];
-};
-
-
-/**
- * Create new transaction. Application would normally use
- * #pjsip_endpt_create_tsx rather than this function.
- *
- * @param pool Pool to use by the transaction.
- * @param endpt Endpoint.
- * @param p_tsx Pointer to return the transaction.
- *
- * @return PJ_SUCCESS or the appropriate error code.
- *
- * @see pjsip_endpt_create_tsx
- *
- */
-PJ_DEF(pj_status_t) pjsip_tsx_create( pj_pool_t *pool,
- pjsip_endpoint *endpt,
- pjsip_transaction **p_tsx);
-
-/**
- * Init transaction as UAC from the specified transmit data (\c tdata).
- * The transmit data must have a valid \c Request-Line and \c CSeq header.
- * If \c Route headers are present, it will be used to calculate remote
- * destination.
- *
- * If \c Via header does not exist, it will be created along with a unique
- * \c branch parameter. If it exists and contains branch parameter, then
- * the \c branch parameter will be used as is as the transaction key.
- *
- * The \c Route headers in the transmit data, if present, are used to
- * calculate remote destination.
- *
- * At the end of the function, the transaction will start resolving the
- * addresses of remote server to contact. Transport will be acquired as soon
- * as the resolving job completes.
- *
- * @param tsx The transaction.
- * @param tdata The transmit data.
- *
- * @return PJ_SUCCESS if successfull.
- */
-PJ_DECL(pj_status_t) pjsip_tsx_init_uac( pjsip_transaction *tsx,
- pjsip_tx_data *tdata);
-
-/**
- * Init transaction as UAS.
- *
- * @param tsx The transaction to be initialized.
- * @param rdata The received incoming request.
- *
- * @return PJ_SUCCESS if successfull.
- */
-PJ_DECL(pj_status_t) pjsip_tsx_init_uas( pjsip_transaction *tsx,
- pjsip_rx_data *rdata);
-
-/**
- * Process incoming message for this transaction.
- *
- * @param tsx The transaction.
- * @param rdata The incoming message.
- */
-PJ_DECL(void) pjsip_tsx_on_rx_msg( pjsip_transaction *tsx,
- pjsip_rx_data *rdata);
-
-/**
- * Transmit message with this transaction.
- *
- * @param tsx The transaction.
- * @param tdata The outgoing message.
- */
-PJ_DECL(void) pjsip_tsx_on_tx_msg( pjsip_transaction *tsx,
- pjsip_tx_data *tdata);
-
-
-/**
- * Transmit ACK message for 2xx/INVITE with this transaction. The ACK for
- * non-2xx/INVITE is automatically sent by the transaction.
- * This operation is only valid if the transaction is configured to handle ACK
- * (tsx->handle_ack is non-zero). If this attribute is not set, then the
- * transaction will comply with RFC-3261, i.e. it will set itself to
- * TERMINATED state when it receives 2xx/INVITE.
- *
- * @param tsx The transaction.
- * @param tdata The ACK request.
- */
-PJ_DECL(void) pjsip_tsx_on_tx_ack( pjsip_transaction *tsx,
- pjsip_tx_data *tdata);
-
-/**
- * Force terminate transaction.
- *
- * @param tsx The transaction.
- * @param code The status code to report.
- */
-PJ_DECL(void) pjsip_tsx_terminate( pjsip_transaction *tsx,
- int code );
-
-/**
- * Create transaction key, which is used to match incoming requests
- * or response (retransmissions) against transactions.
- *
- * @param pool The pool
- * @param key Output key.
- * @param role The role of the transaction.
- * @param method The method to be put as a key.
- * @param rdata The received data to calculate.
- *
- * @return PJ_SUCCESS or the appropriate error code.
- */
-PJ_DECL(pj_status_t) pjsip_tsx_create_key( pj_pool_t *pool,
- pj_str_t *key,
- pjsip_role_e role,
- const pjsip_method *method,
- const pjsip_rx_data *rdata );
-
-
-/**
- * @}
- */
-
-/*
- * Internal.
- */
-
-/*
- * Get the string name for the state.
- */
-PJ_DECL(const char *) pjsip_tsx_state_str(pjsip_tsx_state_e state);
-
-/*
- * Get the role name.
- */
-PJ_DECL(const char *) pjsip_role_name(pjsip_role_e role);
-
-
-/* Thread Local Storage ID for transaction lock (initialized by endpoint) */
-extern long pjsip_tsx_lock_tls_id;
-
-PJ_END_DECL
-
-#endif /* __PJSIP_TRANSACT_H__ */
-
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIP_TRANSACTION_H__ +#define __PJSIP_SIP_TRANSACTION_H__ + +/** + * @file sip_transaction.h + * @brief SIP Transaction + */ + +#include <pjsip/sip_msg.h> +#include <pjsip/sip_resolve.h> +#include <pj/timer.h> + +PJ_BEGIN_DECL + +/** + * @defgroup PJSIP_TRANSACT SIP Transaction + * @ingroup PJSIP + * @{ + */ + +/* Forward decl. */ +struct pjsip_transaction; + + +/** + * Transaction state. + */ +typedef enum pjsip_tsx_state_e +{ + PJSIP_TSX_STATE_NULL, + PJSIP_TSX_STATE_CALLING, + PJSIP_TSX_STATE_TRYING, + PJSIP_TSX_STATE_PROCEEDING, + PJSIP_TSX_STATE_COMPLETED, + PJSIP_TSX_STATE_CONFIRMED, + PJSIP_TSX_STATE_TERMINATED, + PJSIP_TSX_STATE_DESTROYED, + PJSIP_TSX_STATE_MAX, +} pjsip_tsx_state_e; + + +/** + * State of the transport in the transaction. + * The transport is progressing independently of the transaction. + */ +typedef enum pjsip_tsx_transport_state_e +{ + PJSIP_TSX_TRANSPORT_STATE_NULL, + PJSIP_TSX_TRANSPORT_STATE_RESOLVING, + PJSIP_TSX_TRANSPORT_STATE_CONNECTING, + PJSIP_TSX_TRANSPORT_STATE_FINAL, +} pjsip_tsx_transport_state_e; + + +/** + * Transaction state. + */ +struct pjsip_transaction +{ + /* + * Administrivia + */ + pj_pool_t *pool; /**< Pool owned by the tsx. */ + pjsip_endpoint *endpt; /**< Endpoint instance. */ + pj_mutex_t *mutex; /**< Mutex for this tsx. */ + char obj_name[PJ_MAX_OBJ_NAME]; /**< Tsx name. */ + int tracing; /**< Tracing enabled? */ + + /* + * Transaction identification. + */ + pjsip_role_e role; /**< Role (UAS or UAC) */ + pjsip_method method; /**< The method. */ + int cseq; /**< The CSeq */ + pj_str_t transaction_key;/**< hash table key. */ + pj_str_t branch; /**< The branch Id. */ + + /* + * State and status. + */ + int status_code; /**< Last status code seen. */ + pjsip_tsx_state_e state; /**< State. */ + int handle_ack; /**< Should we handle ACK? */ + + /** Handler according to current state. */ + pj_status_t (*state_handler)(struct pjsip_transaction *, pjsip_event *); + + /* + * Transport. + */ + pjsip_tsx_transport_state_e transport_state;/**< Transport's state. */ + pjsip_host_port dest_name; /**< Destination address. */ + pjsip_server_addresses remote_addr; /**< Addresses resolved. */ + int current_addr; /**< Address currently used. */ + + pjsip_transport *transport; /**< Transport to use. */ + + /* + * Messages and timer. + */ + pjsip_tx_data *last_tx; /**< Msg kept for retrans. */ + int has_unsent_msg; /**< Non-zero if tsx need to + transmit msg once resolver + completes. */ + int retransmit_count;/**< Retransmission count. */ + pj_timer_entry retransmit_timer;/**< Retransmit timer. */ + pj_timer_entry timeout_timer; /**< Timeout timer. */ + + /** Module specific data. */ + void *module_data[PJSIP_MAX_MODULE]; +}; + + +/** + * Create new transaction. Application would normally use + * #pjsip_endpt_create_tsx rather than this function. + * + * @param pool Pool to use by the transaction. + * @param endpt Endpoint. + * @param p_tsx Pointer to return the transaction. + * + * @return PJ_SUCCESS or the appropriate error code. + * + * @see pjsip_endpt_create_tsx + * + */ +PJ_DEF(pj_status_t) pjsip_tsx_create( pj_pool_t *pool, + pjsip_endpoint *endpt, + pjsip_transaction **p_tsx); + +/** + * Init transaction as UAC from the specified transmit data (\c tdata). + * The transmit data must have a valid \c Request-Line and \c CSeq header. + * If \c Route headers are present, it will be used to calculate remote + * destination. + * + * If \c Via header does not exist, it will be created along with a unique + * \c branch parameter. If it exists and contains branch parameter, then + * the \c branch parameter will be used as is as the transaction key. + * + * The \c Route headers in the transmit data, if present, are used to + * calculate remote destination. + * + * At the end of the function, the transaction will start resolving the + * addresses of remote server to contact. Transport will be acquired as soon + * as the resolving job completes. + * + * @param tsx The transaction. + * @param tdata The transmit data. + * + * @return PJ_SUCCESS if successfull. + */ +PJ_DECL(pj_status_t) pjsip_tsx_init_uac( pjsip_transaction *tsx, + pjsip_tx_data *tdata); + +/** + * Init transaction as UAS. + * + * @param tsx The transaction to be initialized. + * @param rdata The received incoming request. + * + * @return PJ_SUCCESS if successfull. + */ +PJ_DECL(pj_status_t) pjsip_tsx_init_uas( pjsip_transaction *tsx, + pjsip_rx_data *rdata); + +/** + * Process incoming message for this transaction. + * + * @param tsx The transaction. + * @param rdata The incoming message. + */ +PJ_DECL(void) pjsip_tsx_on_rx_msg( pjsip_transaction *tsx, + pjsip_rx_data *rdata); + +/** + * Transmit message with this transaction. + * + * @param tsx The transaction. + * @param tdata The outgoing message. + */ +PJ_DECL(void) pjsip_tsx_on_tx_msg( pjsip_transaction *tsx, + pjsip_tx_data *tdata); + + +/** + * Transmit ACK message for 2xx/INVITE with this transaction. The ACK for + * non-2xx/INVITE is automatically sent by the transaction. + * This operation is only valid if the transaction is configured to handle ACK + * (tsx->handle_ack is non-zero). If this attribute is not set, then the + * transaction will comply with RFC-3261, i.e. it will set itself to + * TERMINATED state when it receives 2xx/INVITE. + * + * @param tsx The transaction. + * @param tdata The ACK request. + */ +PJ_DECL(void) pjsip_tsx_on_tx_ack( pjsip_transaction *tsx, + pjsip_tx_data *tdata); + +/** + * Force terminate transaction. + * + * @param tsx The transaction. + * @param code The status code to report. + */ +PJ_DECL(void) pjsip_tsx_terminate( pjsip_transaction *tsx, + int code ); + +/** + * Create transaction key, which is used to match incoming requests + * or response (retransmissions) against transactions. + * + * @param pool The pool + * @param key Output key. + * @param role The role of the transaction. + * @param method The method to be put as a key. + * @param rdata The received data to calculate. + * + * @return PJ_SUCCESS or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsip_tsx_create_key( pj_pool_t *pool, + pj_str_t *key, + pjsip_role_e role, + const pjsip_method *method, + const pjsip_rx_data *rdata ); + + +/** + * @} + */ + +/* + * Internal. + */ + +/* + * Get the string name for the state. + */ +PJ_DECL(const char *) pjsip_tsx_state_str(pjsip_tsx_state_e state); + +/* + * Get the role name. + */ +PJ_DECL(const char *) pjsip_role_name(pjsip_role_e role); + + +/* Thread Local Storage ID for transaction lock (initialized by endpoint) */ +extern long pjsip_tsx_lock_tls_id; + +PJ_END_DECL + +#endif /* __PJSIP_TRANSACT_H__ */ + diff --git a/pjsip/include/pjsip/sip_transport.h b/pjsip/include/pjsip/sip_transport.h index 869641bd..dac608ff 100644 --- a/pjsip/include/pjsip/sip_transport.h +++ b/pjsip/include/pjsip/sip_transport.h @@ -1,635 +1,635 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIP_TRANSPORT_H__
-#define __PJSIP_SIP_TRANSPORT_H__
-
-/**
- * @file sip_transport.h
- * @brief SIP Transport
- */
-
-#include <pjsip/sip_msg.h>
-#include <pjsip/sip_parser.h>
-#include <pj/sock.h>
-#include <pj/list.h>
-#include <pj/ioqueue.h>
-#include <pj/timer.h>
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJSIP_TRANSPORT SIP Transport
- * @ingroup PJSIP
- *
- * This is the low-level transport layer. Application normally won't need to
- * use this function, but instead can use transaction or higher layer API to
- * send and receive messages.
- *
- * @{
- */
-
-/*****************************************************************************
- *
- * GENERAL TRANSPORT (NAMES, TYPES, ETC.)
- *
- *****************************************************************************/
-
-/**
- * Flags for SIP transports.
- */
-enum pjsip_transport_flags_e
-{
- PJSIP_TRANSPORT_RELIABLE = 1, /**< Transport is reliable. */
- PJSIP_TRANSPORT_SECURE = 2, /**< Transport is secure. */
- PJSIP_TRANSPORT_DATAGRAM = 4, /**< Datagram based transport. */
-};
-
-/**
- * Check if transport tp is reliable.
- */
-#define PJSIP_TRANSPORT_IS_RELIABLE(tp) \
- ((tp)->flag & PJSIP_TRANSPORT_RELIABLE)
-
-/**
- * Get the transport type from the transport name.
- *
- * @param name Transport name, such as "TCP", or "UDP".
- *
- * @return The transport type, or PJSIP_TRANSPORT_UNSPECIFIED if
- * the name is not recognized as the name of supported
- * transport.
- */
-PJ_DECL(pjsip_transport_type_e)
-pjsip_transport_get_type_from_name(const pj_str_t *name);
-
-/**
- * Get the transport type for the specified flags.
- *
- * @param flag The transport flag.
- *
- * @return Transport type.
- */
-PJ_DECL(pjsip_transport_type_e)
-pjsip_transport_get_type_from_flag(unsigned flag);
-
-/**
- * Get transport flag from type.
- *
- * @param type Transport type.
- *
- * @return Transport flags.
- */
-PJ_DECL(unsigned)
-pjsip_transport_get_flag_from_type( pjsip_transport_type_e type );
-
-/**
- * Get the default SIP port number for the specified type.
- *
- * @param type Transport type.
- *
- * @return The port number, which is the default SIP port number for
- * the specified type.
- */
-PJ_DECL(int)
-pjsip_transport_get_default_port_for_type(pjsip_transport_type_e type);
-
-
-/*****************************************************************************
- *
- * RECEIVE DATA BUFFER.
- *
- *****************************************************************************/
-
-/**
- * A customized ioqueue async operation key which is used by transport
- * to locate rdata when a pending read operation completes.
- */
-typedef struct pjsip_rx_data_op_key
-{
- pj_ioqueue_op_key_t op_key;
- pjsip_rx_data *rdata;
-} pjsip_rx_data_op_key;
-
-
-/**
- * Incoming message buffer.
- * This structure keep all the information regarding the received message. This
- * buffer lifetime is only very short, normally after the transaction has been
- * called, this buffer will be deleted/recycled. So care must be taken when
- * allocating storage from the pool of this buffer.
- */
-struct pjsip_rx_data
-{
-
- /**
- * tp_info is part of rdata that remains static for the duration of the
- * buffer. It is initialized when the buffer was created by transport.
- */
- struct
- {
- /** Memory pool for this buffer. */
- pj_pool_t *pool;
-
- /** The transport object which received this packet. */
- pjsip_transport *transport;
-
- /** Ioqueue key. */
- pjsip_rx_data_op_key op_key;
-
- } tp_info;
-
-
- /**
- * pkt_info is initialized by transport when it receives an incoming
- * packet.
- */
- struct
- {
- /** Time when the message was received. */
- pj_time_val timestamp;
-
- /** Pointer to the original packet. */
- char packet[PJSIP_MAX_PKT_LEN];
-
- /** Zero termination for the packet. */
- pj_uint32_t zero;
-
- /** The length of the packet received. */
- int len;
-
- /** The source address from which the packet was received. */
- pj_sockaddr_in addr;
-
- /** The length of the source address. */
- int addr_len;
-
- } pkt_info;
-
-
- /**
- * msg_info is initialized by transport mgr (tpmgr) before this buffer
- * is passed to endpoint.
- */
- struct
- {
- /** Start of msg buffer. */
- char *msg_buf;
-
- /** Length fo message. */
- int len;
-
- /** The parsed message, if any. */
- pjsip_msg *msg;
-
- /** The Call-ID header as found in the message. */
- pj_str_t call_id;
-
- /** The From header as found in the message. */
- pjsip_from_hdr *from;
-
- /** The To header as found in the message. */
- pjsip_to_hdr *to;
-
- /** The topmost Via header as found in the message. */
- pjsip_via_hdr *via;
-
- /** The CSeq header as found in the message. */
- pjsip_cseq_hdr *cseq;
-
- /** Max forwards header. */
- pjsip_max_forwards_hdr *max_fwd;
-
- /** The first route header. */
- pjsip_route_hdr *route;
-
- /** The first record-route header. */
- pjsip_rr_hdr *record_route;
-
- /** Content-type header. */
- pjsip_ctype_hdr *ctype;
-
- /** Content-length header. */
- pjsip_clen_hdr *clen;
-
- /** The first Require header. */
- pjsip_require_hdr *require;
-
- /** The list of error generated by the parser when parsing
- this message.
- */
- pjsip_parser_err_report parse_err;
-
- } msg_info;
-
-
- /**
- * endpt_info is initialized by endpoint after this buffer reaches
- * endpoint.
- */
- struct
- {
- /**
- * This the transaction key generated for the message.
- */
- pj_str_t key;
-
- } endpt_info;
-
-};
-
-
-/*****************************************************************************
- *
- * TRANSMIT DATA BUFFER MANIPULATION.
- *
- *****************************************************************************/
-
-/** Customized ioqueue async operation key, used by transport to keep
- * callback parameters.
- */
-typedef struct pjsip_tx_data_op_key
-{
- pj_ioqueue_op_key_t key;
- pjsip_tx_data *tdata;
- void *token;
- void (*callback)(pjsip_transport*,void*,pj_ssize_t);
-} pjsip_tx_data_op_key;
-
-
-/**
- * Data structure for sending outgoing message. Application normally creates
- * this buffer by calling #pjsip_endpt_create_tdata.
- *
- * The lifetime of this buffer is controlled by the reference counter in this
- * structure, which is manipulated by calling #pjsip_tx_data_add_ref and
- * #pjsip_tx_data_dec_ref. When the reference counter has reached zero, then
- * this buffer will be destroyed.
- *
- * A transaction object normally will add reference counter to this buffer
- * when application calls #pjsip_tsx_on_tx_msg, because it needs to keep the
- * message for retransmission. The transaction will release the reference
- * counter once its state has reached final state.
- */
-struct pjsip_tx_data
-{
- /** This is for transmission queue; it's managed by transports. */
- PJ_DECL_LIST_MEMBER(struct pjsip_tx_data);
-
- /** Memory pool for this buffer. */
- pj_pool_t *pool;
-
- /** A name to identify this buffer. */
- char obj_name[PJ_MAX_OBJ_NAME];
-
- /** For response message, this contains the reference to timestamp when
- * the original request message was received. The value of this field
- * is set when application creates response message to a request by
- * calling #pjsip_endpt_create_response.
- */
- pj_time_val rx_timestamp;
-
- /** The transport manager for this buffer. */
- pjsip_tpmgr *mgr;
-
- /** Ioqueue asynchronous operation key. */
- pjsip_tx_data_op_key op_key;
-
- /** Lock object. */
- pj_lock_t *lock;
-
- /** The message in this buffer. */
- pjsip_msg *msg;
-
- /** Buffer to the printed text representation of the message. When the
- * content of this buffer is set, then the transport will send the content
- * of this buffer instead of re-printing the message structure. If the
- * message structure has changed, then application must invalidate this
- * buffer by calling #pjsip_tx_data_invalidate_msg.
- */
- pjsip_buffer buf;
-
- /** Reference counter. */
- pj_atomic_t *ref_cnt;
-
- /** Being processed by transport? */
- int is_pending;
-
- /** Transport manager internal. */
- void *token;
- void (*cb)(void*, pjsip_tx_data*, pj_ssize_t);
-};
-
-
-/**
- * Create a new, blank transmit buffer. The reference count is initialized
- * to zero.
- *
- * @param mgr The transport manager.
- * @param tdata Pointer to receive transmit data.
- *
- * @return PJ_SUCCESS, or the appropriate error code.
- *
- * @see pjsip_endpt_create_tdata
- */
-pj_status_t pjsip_tx_data_create( pjsip_tpmgr *mgr,
- pjsip_tx_data **tdata );
-
-/**
- * Add reference counter to the transmit buffer. The reference counter controls
- * the life time of the buffer, ie. when the counter reaches zero, then it
- * will be destroyed.
- *
- * @param tdata The transmit buffer.
- */
-PJ_DECL(void) pjsip_tx_data_add_ref( pjsip_tx_data *tdata );
-
-/**
- * Decrement reference counter of the transmit buffer.
- * When the transmit buffer is no longer used, it will be destroyed.
- *
- * @param tdata The transmit buffer data.
- */
-PJ_DECL(void) pjsip_tx_data_dec_ref( pjsip_tx_data *tdata );
-
-/**
- * Check if transmit data buffer contains a valid message.
- *
- * @param tdata The transmit buffer.
- */
-PJ_DECL(pj_bool_t) pjsip_tx_data_is_valid( pjsip_tx_data *tdata );
-
-/**
- * Invalidate the print buffer to force message to be re-printed. Call
- * when the message has changed after it has been printed to buffer. The
- * message is printed to buffer normally by transport when it is about to be
- * sent to the wire. Subsequent sending of the message will not cause
- * the message to be re-printed, unless application invalidates the buffer
- * by calling this function.
- *
- * @param tdata The transmit buffer.
- */
-PJ_DECL(void) pjsip_tx_data_invalidate_msg( pjsip_tx_data *tdata );
-
-
-/*****************************************************************************
- *
- * TRANSPORT
- *
- *****************************************************************************/
-
-/**
- * This structure represent the "public" interface of a SIP transport.
- * Applications normally extend this structure to include transport
- * specific members.
- */
-typedef struct pjsip_transport
-{
- char obj_name[PJ_MAX_OBJ_NAME]; /**< Name. */
-
- pj_pool_t *pool; /**< Pool used by transport. */
- pj_atomic_t *ref_cnt; /**< Reference counter. */
- pj_lock_t *lock; /**< Lock object. */
- int tracing; /**< Tracing enabled? */
-
- pjsip_transport_type_e type; /**< Transport type. */
- char type_name[8]; /**< Type name. */
- unsigned flag; /**< #pjsip_transport_flags_e */
-
- pj_sockaddr_in local_addr; /**< Bound address. */
- pj_sockaddr_in public_addr; /**< STUN addres. */
- pj_sockaddr_in rem_addr; /**< Remote addr (zero for UDP) */
-
- pjsip_endpoint *endpt; /**< Endpoint instance. */
- pjsip_tpmgr *tpmgr; /**< Transport manager. */
- pj_timer_entry idle_timer; /**< Timer when ref cnt is zero.*/
-
- /**
- * Function to be called by transport manager to send SIP message.
- *
- * @param transport The transport to send the message.
- * @param packet The buffer to send.
- * @param length The length of the buffer to send.
- * @param op_key Completion token, which will be supplied to
- * caller when pending send operation completes.
- * @param rem_addr The remote destination address.
- * @param callback If supplied, the callback will be called
- * once a pending transmission has completed. If
- * the function completes immediately (i.e. return
- * code is not PJ_EPENDING), the callback will not
- * be called.
- *
- * @return Should return PJ_SUCCESS only if data has been
- * succesfully queued to operating system for
- * transmission. Otherwise it may return PJ_EPENDING
- * if the underlying transport can not send the
- * data immediately and will send it later, which in
- * this case caller doesn't have to do anything
- * except wait the calback to be called, if it
- * supplies one.
- * Other return values indicate the error code.
- */
- pj_status_t (*send_msg)(pjsip_transport *transport,
- pjsip_tx_data *tdata,
- const pj_sockaddr_in *rem_addr,
- void *token,
- void (*callback)(pjsip_transport *transport,
- void *token,
- pj_ssize_t sent_bytes));
-
- /**
- * Destroy this transport.
- */
- pj_status_t (*destroy)(pjsip_transport *transport);
-
- /*
- * Application may extend this structure..
- */
-} pjsip_transport;
-
-
-/**
- * Register a transport.
- */
-PJ_DECL(pj_status_t) pjsip_transport_register( pjsip_tpmgr *mgr,
- pjsip_transport *tp );
-
-
-/**
- * Unregister transport. This will eventually call the transport to
- * destroy itself.
- */
-PJ_DECL(pj_status_t) pjsip_transport_unregister( pjsip_tpmgr *mgr,
- pjsip_transport *tp);
-
-/**
- * Add ref.
- */
-PJ_DECL(pj_status_t) pjsip_transport_add_ref( pjsip_transport *tp );
-
-/**
- * Dec ref.
- */
-PJ_DECL(pj_status_t) pjsip_transport_dec_ref( pjsip_transport *tp );
-
-
-/**
- * Call for incoming message.
- */
-PJ_DECL(pj_ssize_t) pjsip_tpmgr_receive_packet(pjsip_tpmgr *mgr,
- pjsip_rx_data *rdata);
-
-
-/*****************************************************************************
- *
- * TRANSPORT FACTORY
- *
- *****************************************************************************/
-
-
-/**
- * Transport factory.
- */
-typedef struct pjsip_tpfactory pjsip_tpfactory;
-
-/**
- * Transport factory.
- */
-struct pjsip_tpfactory
-{
- /* This list is managed by transport manager. */
- PJ_DECL_LIST_MEMBER(struct pjsip_tpfactory);
-
- pj_pool_t *pool;
- pj_lock_t *lock;
-
- pjsip_transport_type_e type;
- char type_name[8];
- unsigned flag;
-
- pj_sockaddr_in local_addr;
- pj_sockaddr_in public_addr;
-
- /**
- * Create new outbound connection.
- */
- pj_status_t (*create_transport)(pjsip_tpfactory *factory,
- pjsip_tpmgr *mgr,
- pjsip_endpoint *endpt,
- const pj_sockaddr_in *rem_addr,
- pjsip_transport **transport);
-
- /*
- * Application may extend this structure..
- */
-};
-
-
-
-/**
- * Register a transport factory.
- *
- * @param mgr The transport manager.
- * @param factory Transport factory.
- *
- * @return PJ_SUCCESS if listener was successfully created.
- */
-PJ_DECL(pj_status_t) pjsip_tpmgr_register_tpfactory(pjsip_tpmgr *mgr,
- pjsip_tpfactory *tpf);
-
-/**
- * Unregister factory.
- */
-PJ_DECL(pj_status_t) pjsip_tpmgr_unregister_tpfactory(pjsip_tpmgr *mgr,
- pjsip_tpfactory *tpf);
-
-
-/*****************************************************************************
- *
- * TRANSPORT MANAGER
- *
- *****************************************************************************/
-
-/**
- * Create a new transport manager.
- *
- * @param pool Pool.
- * @param endpt Endpoint instance.
- * @param cb Callback to receive incoming message.
- * @param p_mgr Pointer to receive the new transport manager.
- *
- * @return PJ_SUCCESS or the appropriate error code on error.
- */
-PJ_DECL(pj_status_t) pjsip_tpmgr_create( pj_pool_t *pool,
- pjsip_endpoint * endpt,
- void (*cb)(pjsip_endpoint*,
- pj_status_t,
- pjsip_rx_data *),
- pjsip_tpmgr **p_mgr);
-
-
-/**
- * Destroy transport manager.
- */
-PJ_DECL(pj_status_t) pjsip_tpmgr_destroy(pjsip_tpmgr *mgr);
-
-
-/**
- * Dump transport info.
- */
-PJ_DECL(void) pjsip_tpmgr_dump_transports(pjsip_tpmgr *mgr);
-
-
-/*****************************************************************************
- *
- * PUBLIC API
- *
- *****************************************************************************/
-
-
-/**
- * Find transport to be used to send message to remote destination. If no
- * suitable transport is found, a new one will be created.
- */
-PJ_DECL(pj_status_t) pjsip_tpmgr_alloc_transport( pjsip_tpmgr *mgr,
- pjsip_transport_type_e type,
- const pj_sockaddr_in *remote,
- pjsip_transport **p_transport );
-
-
-/**
- * Send a SIP message using the specified transport.
- */
-PJ_DECL(pj_status_t) pjsip_transport_send( pjsip_transport *tr,
- pjsip_tx_data *tdata,
- const pj_sockaddr_in *addr,
- void *token,
- void (*cb)(void *token,
- pjsip_tx_data *tdata,
- pj_ssize_t bytes_sent));
-
-
-/**
- * @}
- */
-
-
-PJ_END_DECL
-
-#endif /* __PJSIP_SIP_TRANSPORT_H__ */
-
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIP_TRANSPORT_H__ +#define __PJSIP_SIP_TRANSPORT_H__ + +/** + * @file sip_transport.h + * @brief SIP Transport + */ + +#include <pjsip/sip_msg.h> +#include <pjsip/sip_parser.h> +#include <pj/sock.h> +#include <pj/list.h> +#include <pj/ioqueue.h> +#include <pj/timer.h> + +PJ_BEGIN_DECL + +/** + * @defgroup PJSIP_TRANSPORT SIP Transport + * @ingroup PJSIP + * + * This is the low-level transport layer. Application normally won't need to + * use this function, but instead can use transaction or higher layer API to + * send and receive messages. + * + * @{ + */ + +/***************************************************************************** + * + * GENERAL TRANSPORT (NAMES, TYPES, ETC.) + * + *****************************************************************************/ + +/** + * Flags for SIP transports. + */ +enum pjsip_transport_flags_e +{ + PJSIP_TRANSPORT_RELIABLE = 1, /**< Transport is reliable. */ + PJSIP_TRANSPORT_SECURE = 2, /**< Transport is secure. */ + PJSIP_TRANSPORT_DATAGRAM = 4, /**< Datagram based transport. */ +}; + +/** + * Check if transport tp is reliable. + */ +#define PJSIP_TRANSPORT_IS_RELIABLE(tp) \ + ((tp)->flag & PJSIP_TRANSPORT_RELIABLE) + +/** + * Get the transport type from the transport name. + * + * @param name Transport name, such as "TCP", or "UDP". + * + * @return The transport type, or PJSIP_TRANSPORT_UNSPECIFIED if + * the name is not recognized as the name of supported + * transport. + */ +PJ_DECL(pjsip_transport_type_e) +pjsip_transport_get_type_from_name(const pj_str_t *name); + +/** + * Get the transport type for the specified flags. + * + * @param flag The transport flag. + * + * @return Transport type. + */ +PJ_DECL(pjsip_transport_type_e) +pjsip_transport_get_type_from_flag(unsigned flag); + +/** + * Get transport flag from type. + * + * @param type Transport type. + * + * @return Transport flags. + */ +PJ_DECL(unsigned) +pjsip_transport_get_flag_from_type( pjsip_transport_type_e type ); + +/** + * Get the default SIP port number for the specified type. + * + * @param type Transport type. + * + * @return The port number, which is the default SIP port number for + * the specified type. + */ +PJ_DECL(int) +pjsip_transport_get_default_port_for_type(pjsip_transport_type_e type); + + +/***************************************************************************** + * + * RECEIVE DATA BUFFER. + * + *****************************************************************************/ + +/** + * A customized ioqueue async operation key which is used by transport + * to locate rdata when a pending read operation completes. + */ +typedef struct pjsip_rx_data_op_key +{ + pj_ioqueue_op_key_t op_key; + pjsip_rx_data *rdata; +} pjsip_rx_data_op_key; + + +/** + * Incoming message buffer. + * This structure keep all the information regarding the received message. This + * buffer lifetime is only very short, normally after the transaction has been + * called, this buffer will be deleted/recycled. So care must be taken when + * allocating storage from the pool of this buffer. + */ +struct pjsip_rx_data +{ + + /** + * tp_info is part of rdata that remains static for the duration of the + * buffer. It is initialized when the buffer was created by transport. + */ + struct + { + /** Memory pool for this buffer. */ + pj_pool_t *pool; + + /** The transport object which received this packet. */ + pjsip_transport *transport; + + /** Ioqueue key. */ + pjsip_rx_data_op_key op_key; + + } tp_info; + + + /** + * pkt_info is initialized by transport when it receives an incoming + * packet. + */ + struct + { + /** Time when the message was received. */ + pj_time_val timestamp; + + /** Pointer to the original packet. */ + char packet[PJSIP_MAX_PKT_LEN]; + + /** Zero termination for the packet. */ + pj_uint32_t zero; + + /** The length of the packet received. */ + int len; + + /** The source address from which the packet was received. */ + pj_sockaddr_in addr; + + /** The length of the source address. */ + int addr_len; + + } pkt_info; + + + /** + * msg_info is initialized by transport mgr (tpmgr) before this buffer + * is passed to endpoint. + */ + struct + { + /** Start of msg buffer. */ + char *msg_buf; + + /** Length fo message. */ + int len; + + /** The parsed message, if any. */ + pjsip_msg *msg; + + /** The Call-ID header as found in the message. */ + pj_str_t call_id; + + /** The From header as found in the message. */ + pjsip_from_hdr *from; + + /** The To header as found in the message. */ + pjsip_to_hdr *to; + + /** The topmost Via header as found in the message. */ + pjsip_via_hdr *via; + + /** The CSeq header as found in the message. */ + pjsip_cseq_hdr *cseq; + + /** Max forwards header. */ + pjsip_max_forwards_hdr *max_fwd; + + /** The first route header. */ + pjsip_route_hdr *route; + + /** The first record-route header. */ + pjsip_rr_hdr *record_route; + + /** Content-type header. */ + pjsip_ctype_hdr *ctype; + + /** Content-length header. */ + pjsip_clen_hdr *clen; + + /** The first Require header. */ + pjsip_require_hdr *require; + + /** The list of error generated by the parser when parsing + this message. + */ + pjsip_parser_err_report parse_err; + + } msg_info; + + + /** + * endpt_info is initialized by endpoint after this buffer reaches + * endpoint. + */ + struct + { + /** + * This the transaction key generated for the message. + */ + pj_str_t key; + + } endpt_info; + +}; + + +/***************************************************************************** + * + * TRANSMIT DATA BUFFER MANIPULATION. + * + *****************************************************************************/ + +/** Customized ioqueue async operation key, used by transport to keep + * callback parameters. + */ +typedef struct pjsip_tx_data_op_key +{ + pj_ioqueue_op_key_t key; + pjsip_tx_data *tdata; + void *token; + void (*callback)(pjsip_transport*,void*,pj_ssize_t); +} pjsip_tx_data_op_key; + + +/** + * Data structure for sending outgoing message. Application normally creates + * this buffer by calling #pjsip_endpt_create_tdata. + * + * The lifetime of this buffer is controlled by the reference counter in this + * structure, which is manipulated by calling #pjsip_tx_data_add_ref and + * #pjsip_tx_data_dec_ref. When the reference counter has reached zero, then + * this buffer will be destroyed. + * + * A transaction object normally will add reference counter to this buffer + * when application calls #pjsip_tsx_on_tx_msg, because it needs to keep the + * message for retransmission. The transaction will release the reference + * counter once its state has reached final state. + */ +struct pjsip_tx_data +{ + /** This is for transmission queue; it's managed by transports. */ + PJ_DECL_LIST_MEMBER(struct pjsip_tx_data); + + /** Memory pool for this buffer. */ + pj_pool_t *pool; + + /** A name to identify this buffer. */ + char obj_name[PJ_MAX_OBJ_NAME]; + + /** For response message, this contains the reference to timestamp when + * the original request message was received. The value of this field + * is set when application creates response message to a request by + * calling #pjsip_endpt_create_response. + */ + pj_time_val rx_timestamp; + + /** The transport manager for this buffer. */ + pjsip_tpmgr *mgr; + + /** Ioqueue asynchronous operation key. */ + pjsip_tx_data_op_key op_key; + + /** Lock object. */ + pj_lock_t *lock; + + /** The message in this buffer. */ + pjsip_msg *msg; + + /** Buffer to the printed text representation of the message. When the + * content of this buffer is set, then the transport will send the content + * of this buffer instead of re-printing the message structure. If the + * message structure has changed, then application must invalidate this + * buffer by calling #pjsip_tx_data_invalidate_msg. + */ + pjsip_buffer buf; + + /** Reference counter. */ + pj_atomic_t *ref_cnt; + + /** Being processed by transport? */ + int is_pending; + + /** Transport manager internal. */ + void *token; + void (*cb)(void*, pjsip_tx_data*, pj_ssize_t); +}; + + +/** + * Create a new, blank transmit buffer. The reference count is initialized + * to zero. + * + * @param mgr The transport manager. + * @param tdata Pointer to receive transmit data. + * + * @return PJ_SUCCESS, or the appropriate error code. + * + * @see pjsip_endpt_create_tdata + */ +pj_status_t pjsip_tx_data_create( pjsip_tpmgr *mgr, + pjsip_tx_data **tdata ); + +/** + * Add reference counter to the transmit buffer. The reference counter controls + * the life time of the buffer, ie. when the counter reaches zero, then it + * will be destroyed. + * + * @param tdata The transmit buffer. + */ +PJ_DECL(void) pjsip_tx_data_add_ref( pjsip_tx_data *tdata ); + +/** + * Decrement reference counter of the transmit buffer. + * When the transmit buffer is no longer used, it will be destroyed. + * + * @param tdata The transmit buffer data. + */ +PJ_DECL(void) pjsip_tx_data_dec_ref( pjsip_tx_data *tdata ); + +/** + * Check if transmit data buffer contains a valid message. + * + * @param tdata The transmit buffer. + */ +PJ_DECL(pj_bool_t) pjsip_tx_data_is_valid( pjsip_tx_data *tdata ); + +/** + * Invalidate the print buffer to force message to be re-printed. Call + * when the message has changed after it has been printed to buffer. The + * message is printed to buffer normally by transport when it is about to be + * sent to the wire. Subsequent sending of the message will not cause + * the message to be re-printed, unless application invalidates the buffer + * by calling this function. + * + * @param tdata The transmit buffer. + */ +PJ_DECL(void) pjsip_tx_data_invalidate_msg( pjsip_tx_data *tdata ); + + +/***************************************************************************** + * + * TRANSPORT + * + *****************************************************************************/ + +/** + * This structure represent the "public" interface of a SIP transport. + * Applications normally extend this structure to include transport + * specific members. + */ +typedef struct pjsip_transport +{ + char obj_name[PJ_MAX_OBJ_NAME]; /**< Name. */ + + pj_pool_t *pool; /**< Pool used by transport. */ + pj_atomic_t *ref_cnt; /**< Reference counter. */ + pj_lock_t *lock; /**< Lock object. */ + int tracing; /**< Tracing enabled? */ + + pjsip_transport_type_e type; /**< Transport type. */ + char type_name[8]; /**< Type name. */ + unsigned flag; /**< #pjsip_transport_flags_e */ + + pj_sockaddr_in local_addr; /**< Bound address. */ + pj_sockaddr_in public_addr; /**< STUN addres. */ + pj_sockaddr_in rem_addr; /**< Remote addr (zero for UDP) */ + + pjsip_endpoint *endpt; /**< Endpoint instance. */ + pjsip_tpmgr *tpmgr; /**< Transport manager. */ + pj_timer_entry idle_timer; /**< Timer when ref cnt is zero.*/ + + /** + * Function to be called by transport manager to send SIP message. + * + * @param transport The transport to send the message. + * @param packet The buffer to send. + * @param length The length of the buffer to send. + * @param op_key Completion token, which will be supplied to + * caller when pending send operation completes. + * @param rem_addr The remote destination address. + * @param callback If supplied, the callback will be called + * once a pending transmission has completed. If + * the function completes immediately (i.e. return + * code is not PJ_EPENDING), the callback will not + * be called. + * + * @return Should return PJ_SUCCESS only if data has been + * succesfully queued to operating system for + * transmission. Otherwise it may return PJ_EPENDING + * if the underlying transport can not send the + * data immediately and will send it later, which in + * this case caller doesn't have to do anything + * except wait the calback to be called, if it + * supplies one. + * Other return values indicate the error code. + */ + pj_status_t (*send_msg)(pjsip_transport *transport, + pjsip_tx_data *tdata, + const pj_sockaddr_in *rem_addr, + void *token, + void (*callback)(pjsip_transport *transport, + void *token, + pj_ssize_t sent_bytes)); + + /** + * Destroy this transport. + */ + pj_status_t (*destroy)(pjsip_transport *transport); + + /* + * Application may extend this structure.. + */ +} pjsip_transport; + + +/** + * Register a transport. + */ +PJ_DECL(pj_status_t) pjsip_transport_register( pjsip_tpmgr *mgr, + pjsip_transport *tp ); + + +/** + * Unregister transport. This will eventually call the transport to + * destroy itself. + */ +PJ_DECL(pj_status_t) pjsip_transport_unregister( pjsip_tpmgr *mgr, + pjsip_transport *tp); + +/** + * Add ref. + */ +PJ_DECL(pj_status_t) pjsip_transport_add_ref( pjsip_transport *tp ); + +/** + * Dec ref. + */ +PJ_DECL(pj_status_t) pjsip_transport_dec_ref( pjsip_transport *tp ); + + +/** + * Call for incoming message. + */ +PJ_DECL(pj_ssize_t) pjsip_tpmgr_receive_packet(pjsip_tpmgr *mgr, + pjsip_rx_data *rdata); + + +/***************************************************************************** + * + * TRANSPORT FACTORY + * + *****************************************************************************/ + + +/** + * Transport factory. + */ +typedef struct pjsip_tpfactory pjsip_tpfactory; + +/** + * Transport factory. + */ +struct pjsip_tpfactory +{ + /* This list is managed by transport manager. */ + PJ_DECL_LIST_MEMBER(struct pjsip_tpfactory); + + pj_pool_t *pool; + pj_lock_t *lock; + + pjsip_transport_type_e type; + char type_name[8]; + unsigned flag; + + pj_sockaddr_in local_addr; + pj_sockaddr_in public_addr; + + /** + * Create new outbound connection. + */ + pj_status_t (*create_transport)(pjsip_tpfactory *factory, + pjsip_tpmgr *mgr, + pjsip_endpoint *endpt, + const pj_sockaddr_in *rem_addr, + pjsip_transport **transport); + + /* + * Application may extend this structure.. + */ +}; + + + +/** + * Register a transport factory. + * + * @param mgr The transport manager. + * @param factory Transport factory. + * + * @return PJ_SUCCESS if listener was successfully created. + */ +PJ_DECL(pj_status_t) pjsip_tpmgr_register_tpfactory(pjsip_tpmgr *mgr, + pjsip_tpfactory *tpf); + +/** + * Unregister factory. + */ +PJ_DECL(pj_status_t) pjsip_tpmgr_unregister_tpfactory(pjsip_tpmgr *mgr, + pjsip_tpfactory *tpf); + + +/***************************************************************************** + * + * TRANSPORT MANAGER + * + *****************************************************************************/ + +/** + * Create a new transport manager. + * + * @param pool Pool. + * @param endpt Endpoint instance. + * @param cb Callback to receive incoming message. + * @param p_mgr Pointer to receive the new transport manager. + * + * @return PJ_SUCCESS or the appropriate error code on error. + */ +PJ_DECL(pj_status_t) pjsip_tpmgr_create( pj_pool_t *pool, + pjsip_endpoint * endpt, + void (*cb)(pjsip_endpoint*, + pj_status_t, + pjsip_rx_data *), + pjsip_tpmgr **p_mgr); + + +/** + * Destroy transport manager. + */ +PJ_DECL(pj_status_t) pjsip_tpmgr_destroy(pjsip_tpmgr *mgr); + + +/** + * Dump transport info. + */ +PJ_DECL(void) pjsip_tpmgr_dump_transports(pjsip_tpmgr *mgr); + + +/***************************************************************************** + * + * PUBLIC API + * + *****************************************************************************/ + + +/** + * Find transport to be used to send message to remote destination. If no + * suitable transport is found, a new one will be created. + */ +PJ_DECL(pj_status_t) pjsip_tpmgr_alloc_transport( pjsip_tpmgr *mgr, + pjsip_transport_type_e type, + const pj_sockaddr_in *remote, + pjsip_transport **p_transport ); + + +/** + * Send a SIP message using the specified transport. + */ +PJ_DECL(pj_status_t) pjsip_transport_send( pjsip_transport *tr, + pjsip_tx_data *tdata, + const pj_sockaddr_in *addr, + void *token, + void (*cb)(void *token, + pjsip_tx_data *tdata, + pj_ssize_t bytes_sent)); + + +/** + * @} + */ + + +PJ_END_DECL + +#endif /* __PJSIP_SIP_TRANSPORT_H__ */ + diff --git a/pjsip/include/pjsip/sip_transport_udp.h b/pjsip/include/pjsip/sip_transport_udp.h index 10ace7fc..99f5ab67 100644 --- a/pjsip/include/pjsip/sip_transport_udp.h +++ b/pjsip/include/pjsip/sip_transport_udp.h @@ -1,68 +1,68 @@ -/* $Id: $ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_TRANSPORT_UDP_H__
-#define __PJSIP_TRANSPORT_UDP_H__
-
-#include <pjsip/sip_transport.h>
-
-PJ_DECL
-
-/**
- * Start UDP transport.
- *
- * @param endpt The SIP endpoint.
- * @param local Local address to bind.
- * @param pub_addr Public address to advertise.
- * @param async_cnt Number of simultaneous async operations.
- * @param p_transport Pointer to receive the transport.
- *
- * @return PJ_SUCCESS when the transport has been successfully
- * started and registered to transport manager, or
- * the appropriate error code.
- */
-PJ_DECL(pj_status_t) pjsip_udp_transport_start(pjsip_endpoint *endpt,
- const pj_sockaddr_in *local,
- const pj_sockaddr_in *pub_addr,
- unsigned async_cnt,
- pjsip_transport **p_transport);
-
-/**
- * Attach UDP socket as a new transport and start the transport.
- *
- * @param endpt The SIP endpoint.
- * @param sock UDP socket to use.
- * @param pub_addr Public address to advertise.
- * @param async_cnt Number of simultaneous async operations.
- * @param p_transport Pointer to receive the transport.
- *
- * @return PJ_SUCCESS when the transport has been successfully
- * started and registered to transport manager, or
- * the appropriate error code.
- */
-PJ_DECL(pj_status_t) pjsip_udp_transport_attach(pjsip_endpoint *endpt,
- pj_sock_t sock,
- const pj_sockaddr_in *pub_addr,
- unsigned async_cnt,
- pjsip_transport **p_transport);
-
-
-PJ_END_DECL
-
-
-#endif /* __PJSIP_TRANSPORT_UDP_H__ */
+/* $Id: $ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_TRANSPORT_UDP_H__ +#define __PJSIP_TRANSPORT_UDP_H__ + +#include <pjsip/sip_transport.h> + +PJ_DECL + +/** + * Start UDP transport. + * + * @param endpt The SIP endpoint. + * @param local Local address to bind. + * @param pub_addr Public address to advertise. + * @param async_cnt Number of simultaneous async operations. + * @param p_transport Pointer to receive the transport. + * + * @return PJ_SUCCESS when the transport has been successfully + * started and registered to transport manager, or + * the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsip_udp_transport_start(pjsip_endpoint *endpt, + const pj_sockaddr_in *local, + const pj_sockaddr_in *pub_addr, + unsigned async_cnt, + pjsip_transport **p_transport); + +/** + * Attach UDP socket as a new transport and start the transport. + * + * @param endpt The SIP endpoint. + * @param sock UDP socket to use. + * @param pub_addr Public address to advertise. + * @param async_cnt Number of simultaneous async operations. + * @param p_transport Pointer to receive the transport. + * + * @return PJ_SUCCESS when the transport has been successfully + * started and registered to transport manager, or + * the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsip_udp_transport_attach(pjsip_endpoint *endpt, + pj_sock_t sock, + const pj_sockaddr_in *pub_addr, + unsigned async_cnt, + pjsip_transport **p_transport); + + +PJ_END_DECL + + +#endif /* __PJSIP_TRANSPORT_UDP_H__ */ diff --git a/pjsip/include/pjsip/sip_types.h b/pjsip/include/pjsip/sip_types.h index 6554b4ce..2f8f2d13 100644 --- a/pjsip/include/pjsip/sip_types.h +++ b/pjsip/include/pjsip/sip_types.h @@ -1,175 +1,175 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIP_TYPES_H__
-#define __PJSIP_SIP_TYPES_H__
-
-#include <pjsip/sip_config.h>
-#include <pj/types.h>
-
-/**
- * Opaque data structure for transports (sip_transport.h).
- */
-typedef struct pjsip_transport pjsip_transport;
-
-/**
- * Opaque data type for transport manager (sip_transport.h).
- */
-typedef struct pjsip_tpmgr pjsip_tpmgr;
-
-/**
- * Transport types.
- */
-typedef enum pjsip_transport_type_e
-{
- /** Unspecified. */
- PJSIP_TRANSPORT_UNSPECIFIED,
-
- /** UDP. */
- PJSIP_TRANSPORT_UDP,
-
- /** TCP. */
- PJSIP_TRANSPORT_TCP,
-
- /** TLS. */
- PJSIP_TRANSPORT_TLS,
-
- /** SCTP. */
- PJSIP_TRANSPORT_SCTP,
-
-} pjsip_transport_type_e;
-
-
-/**
- * Forward declaration for endpoint (sip_endpoint.h).
- */
-typedef struct pjsip_endpoint pjsip_endpoint;
-
-/**
- * Forward declaration for transactions (sip_transaction.h).
- */
-typedef struct pjsip_transaction pjsip_transaction;
-
-/**
- * Forward declaration for events (sip_event.h).
- */
-typedef struct pjsip_event pjsip_event;
-
-/**
- * Forward declaration for transmit data/buffer (sip_transport.h).
- */
-typedef struct pjsip_tx_data pjsip_tx_data;
-
-/**
- * Forward declaration for receive data/buffer (sip_transport.h).
- */
-typedef struct pjsip_rx_data pjsip_rx_data;
-
-/**
- * Forward declaration for message (sip_msg.h).
- */
-typedef struct pjsip_msg pjsip_msg;
-
-/**
- * Forward declaration for header field (sip_msg.h).
- */
-typedef struct pjsip_hdr pjsip_hdr;
-
-/**
- * Forward declaration for URI (sip_uri.h).
- */
-typedef struct pjsip_uri pjsip_uri;
-
-/**
- * Opaque data type for the resolver engine (sip_resolve.h).
- */
-typedef struct pjsip_resolver_t pjsip_resolver_t;
-
-/**
- * Forward declaration for credential.
- */
-typedef struct pjsip_cred_info pjsip_cred_info;
-
-
-/**
- * Forward declaration for module (sip_module.h).
- */
-typedef struct pjsip_module pjsip_module;
-
-/**
- * Transaction role.
- */
-typedef enum pjsip_role_e
-{
- PJSIP_ROLE_UAC, /**< Transaction role is UAC. */
- PJSIP_ROLE_UAS, /**< Transaction role is UAS. */
-} pjsip_role_e;
-
-
-/**
- * General purpose buffer.
- */
-typedef struct pjsip_buffer
-{
- /** The start of the buffer. */
- char *start;
-
- /** Pointer to current end of the buffer, which also indicates the position
- of subsequent buffer write.
- */
- char *cur;
-
- /** The absolute end of the buffer. */
- char *end;
-
-} pjsip_buffer;
-
-
-/**
- * General host:port pair, used for example as Via sent-by.
- */
-typedef struct pjsip_host_port
-{
- unsigned flag; /**< Flags of pjsip_transport_flags_e (not used in Via). */
- unsigned type; /**< Transport type (pjsip_transport_type_e), or zero. */
- pj_str_t host; /**< Host part. */
- int port; /**< Port number. */
-} pjsip_host_port;
-
-
-/**
- * Convert exception ID into pj_status_t status.
- *
- * @param exception_id Exception Id.
- *
- * @return Error code for the specified exception Id.
- */
-PJ_DECL(pj_status_t) pjsip_exception_to_status(int exception_id);
-
-/**
- * Return standard pj_status_t status from current exception.
- */
-#define PJSIP_RETURN_EXCEPTION() pjsip_exception_to_status(PJ_GET_EXCEPTION())
-
-/**
- * Attributes to inform that the function may throw exceptions.
- */
-#define PJSIP_THROW_SPEC(list)
-
-#endif /* __PJSIP_SIP_TYPES_H__ */
-
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIP_TYPES_H__ +#define __PJSIP_SIP_TYPES_H__ + +#include <pjsip/sip_config.h> +#include <pj/types.h> + +/** + * Opaque data structure for transports (sip_transport.h). + */ +typedef struct pjsip_transport pjsip_transport; + +/** + * Opaque data type for transport manager (sip_transport.h). + */ +typedef struct pjsip_tpmgr pjsip_tpmgr; + +/** + * Transport types. + */ +typedef enum pjsip_transport_type_e +{ + /** Unspecified. */ + PJSIP_TRANSPORT_UNSPECIFIED, + + /** UDP. */ + PJSIP_TRANSPORT_UDP, + + /** TCP. */ + PJSIP_TRANSPORT_TCP, + + /** TLS. */ + PJSIP_TRANSPORT_TLS, + + /** SCTP. */ + PJSIP_TRANSPORT_SCTP, + +} pjsip_transport_type_e; + + +/** + * Forward declaration for endpoint (sip_endpoint.h). + */ +typedef struct pjsip_endpoint pjsip_endpoint; + +/** + * Forward declaration for transactions (sip_transaction.h). + */ +typedef struct pjsip_transaction pjsip_transaction; + +/** + * Forward declaration for events (sip_event.h). + */ +typedef struct pjsip_event pjsip_event; + +/** + * Forward declaration for transmit data/buffer (sip_transport.h). + */ +typedef struct pjsip_tx_data pjsip_tx_data; + +/** + * Forward declaration for receive data/buffer (sip_transport.h). + */ +typedef struct pjsip_rx_data pjsip_rx_data; + +/** + * Forward declaration for message (sip_msg.h). + */ +typedef struct pjsip_msg pjsip_msg; + +/** + * Forward declaration for header field (sip_msg.h). + */ +typedef struct pjsip_hdr pjsip_hdr; + +/** + * Forward declaration for URI (sip_uri.h). + */ +typedef struct pjsip_uri pjsip_uri; + +/** + * Opaque data type for the resolver engine (sip_resolve.h). + */ +typedef struct pjsip_resolver_t pjsip_resolver_t; + +/** + * Forward declaration for credential. + */ +typedef struct pjsip_cred_info pjsip_cred_info; + + +/** + * Forward declaration for module (sip_module.h). + */ +typedef struct pjsip_module pjsip_module; + +/** + * Transaction role. + */ +typedef enum pjsip_role_e +{ + PJSIP_ROLE_UAC, /**< Transaction role is UAC. */ + PJSIP_ROLE_UAS, /**< Transaction role is UAS. */ +} pjsip_role_e; + + +/** + * General purpose buffer. + */ +typedef struct pjsip_buffer +{ + /** The start of the buffer. */ + char *start; + + /** Pointer to current end of the buffer, which also indicates the position + of subsequent buffer write. + */ + char *cur; + + /** The absolute end of the buffer. */ + char *end; + +} pjsip_buffer; + + +/** + * General host:port pair, used for example as Via sent-by. + */ +typedef struct pjsip_host_port +{ + unsigned flag; /**< Flags of pjsip_transport_flags_e (not used in Via). */ + unsigned type; /**< Transport type (pjsip_transport_type_e), or zero. */ + pj_str_t host; /**< Host part. */ + int port; /**< Port number. */ +} pjsip_host_port; + + +/** + * Convert exception ID into pj_status_t status. + * + * @param exception_id Exception Id. + * + * @return Error code for the specified exception Id. + */ +PJ_DECL(pj_status_t) pjsip_exception_to_status(int exception_id); + +/** + * Return standard pj_status_t status from current exception. + */ +#define PJSIP_RETURN_EXCEPTION() pjsip_exception_to_status(PJ_GET_EXCEPTION()) + +/** + * Attributes to inform that the function may throw exceptions. + */ +#define PJSIP_THROW_SPEC(list) + +#endif /* __PJSIP_SIP_TYPES_H__ */ + diff --git a/pjsip/include/pjsip/sip_uri.h b/pjsip/include/pjsip/sip_uri.h index b72721f2..0e13b300 100644 --- a/pjsip/include/pjsip/sip_uri.h +++ b/pjsip/include/pjsip/sip_uri.h @@ -1,359 +1,384 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIP_URI_H__
-#define __PJSIP_SIP_URI_H__
-
-/**
- * @file sip_uri.h
- * @brief SIP URL Structures and Manipulations
- */
-
-#include <pjsip/sip_types.h>
-#include <pjsip/sip_config.h>
-#include <pj/list.h>
-
-PJ_BEGIN_DECL
-
-
-/**
- * @defgroup PJSIP_URL URL Structures
- * @brief SIP Url, tel: Url, and generic URI.
- * @ingroup PJSIP_MSG
- * @{
- */
-
-/**
- * Generic parameter, normally used in other_param or header_param.
- */
-typedef struct pjsip_param
-{
- PJ_DECL_LIST_MEMBER(struct pjsip_param); /**< Generic list member. */
- pj_str_t name; /**< Param/header name. */
- pj_str_t value; /**< Param/header value. */
-} pjsip_param;
-
-
-/**
- * Find the specified parameter name in the list. The name will be compared
- * in case-insensitive comparison.
- *
- * @param param_list List of parameters to find.
- * @param name Parameter/header name to find.
- *
- * @return The parameter if found, or NULL.
- */
-PJ_DECL(pjsip_param*) pjsip_param_find( pjsip_param *param_list,
- const pj_str_t *name );
-
-
-/**
- * Find the specified parameter name in the list. The name will be compared
- * in case-insensitive comparison.
- *
- * @param param_list List of parameters to find.
- * @param name Parameter/header name to find.
- *
- * @return The parameter if found, or NULL.
- */
-PJ_DECL(const pjsip_param*) pjsip_param_cfind(const pjsip_param *param_list,
- const pj_str_t *name );
-
-
-/**
- * Duplicate the parameters.
- *
- * @param pool Pool to allocate memory from.
- * @param dst_list Destination list.
- * @param src_list Source list.
- */
-PJ_DECL(void) pjsip_param_clone(pj_pool_t *pool, pjsip_param *dst_list,
- const pjsip_param *src_list);
-
-/**
- * URI context.
- */
-typedef enum pjsip_uri_context_e
-{
- PJSIP_URI_IN_REQ_URI, /**< The URI is in Request URI. */
- PJSIP_URI_IN_FROMTO_HDR, /**< The URI is in From/To header. */
- PJSIP_URI_IN_CONTACT_HDR, /**< The URI is in Contact header. */
- PJSIP_URI_IN_ROUTING_HDR, /**< The URI is in Route/Record-Route header. */
- PJSIP_URI_IN_OTHER, /**< Other context (web page, business card, etc.) */
-} pjsip_uri_context_e;
-
-/**
- * URI 'virtual' function table.
- * All types of URI in this library (such as sip:, sips:, tel:, and name-addr)
- * will have pointer to this table as their first struct member. This table
- * provides polimorphic behaviour to the URI.
- */
-typedef struct pjsip_uri_vptr
-{
- /**
- * Get URI scheme.
- * @param uri the URI (self).
- * @return the URI scheme.
- */
- const pj_str_t* (*p_get_scheme)(const void *uri);
-
- /**
- * Get the URI object contained by this URI, or the URI itself if
- * it doesn't contain another URI.
- * @param uri the URI (self).
- */
- void* (*p_get_uri)(void *uri);
-
- /**
- * Print URI components to the buffer, following the rule of which
- * components are allowed for the context.
- * @param context the context where the URI will be placed.
- * @param uri the URI (self).
- * @param buf the buffer.
- * @param size the size of the buffer.
- * @return the length printed.
- */
- int (*p_print)(pjsip_uri_context_e context,
- const void *uri,
- char *buf, pj_size_t size);
-
- /**
- * Compare two URIs according to the context.
- * @param context the context.
- * @param uri1 the first URI (self).
- * @param uri2 the second URI.
- * @return PJ_SUCCESS if equal, or otherwise the error status which
- * should point to the mismatch part.
- */
- pj_status_t (*p_compare)(pjsip_uri_context_e context,
- const void *uri1, const void *uri2);
-
- /**
- * Clone URI.
- * @param pool the pool.
- * @param the URI to clone (self).
- * @return new URI.
- */
- void *(*p_clone)(pj_pool_t *pool, const void *uri);
-
-} pjsip_uri_vptr;
-
-
-/**
- * The declaration of 'base class' for all URI scheme.
- */
-struct pjsip_uri
-{
- /** All URIs must have URI virtual function table as their first member. */
- pjsip_uri_vptr *vptr;
-};
-
-/**
- * This macro checks that the URL is a "sip:" or "sips:" URL.
- * @param url The URL (pointer to)
- * @return non-zero if TRUE.
- */
-#define PJSIP_URI_SCHEME_IS_SIP(url) \
- (pj_strnicmp2(pjsip_uri_get_scheme(url), "sip", 3)==0)
-
-/**
- * This macro checks that the URL is a "sips:" URL (not SIP).
- * @param url The URL (pointer to)
- * @return non-zero if TRUE.
- */
-#define PJSIP_URI_SCHEME_IS_SIPS(url) \
- (pj_strnicmp2(pjsip_uri_get_scheme(url), "sips", 4)==0)
-
-/**
- * This macro checks that the URL is a "tel:" URL.
- * @param url The URL (pointer to)
- * @return non-zero if TRUE.
- */
-#define PJSIP_URI_SCHEME_IS_TEL(url) \
- (pj_strnicmp2(pjsip_uri_get_scheme(url), "tel", 3)==0)
-
-
-/**
- * SIP and SIPS URL scheme.
- */
-typedef struct pjsip_url
-{
- pjsip_uri_vptr *vptr; /**< Pointer to virtual function table.*/
- pj_str_t user; /**< Optional user part. */
- pj_str_t passwd; /**< Optional password part. */
- pj_str_t host; /**< Host part, always exists. */
- int port; /**< Optional port number, or zero. */
- pj_str_t user_param; /**< Optional user parameter */
- pj_str_t method_param; /**< Optional method parameter. */
- pj_str_t transport_param; /**< Optional transport parameter. */
- int ttl_param; /**< Optional TTL param, or -1. */
- int lr_param; /**< Optional loose routing param, or zero */
- pj_str_t maddr_param; /**< Optional maddr param */
- pjsip_param other_param; /**< Other parameters grouped together. */
- pjsip_param header_param; /**< Optional header parameter. */
-} pjsip_url;
-
-
-/**
- * SIP name-addr, which typically appear in From, To, and Contact header.
- * The SIP name-addr contains a generic URI and a display name.
- */
-typedef struct pjsip_name_addr
-{
- /** Pointer to virtual function table. */
- pjsip_uri_vptr *vptr;
-
- /** Optional display name. */
- pj_str_t display;
-
- /** URI part. */
- pjsip_uri *uri;
-
-} pjsip_name_addr;
-
-
-/**
- * Generic function to get the URI scheme.
- * @param uri the URI object.
- * @return the URI scheme.
- */
-PJ_INLINE(const pj_str_t*) pjsip_uri_get_scheme(const void *uri)
-{
- return (*((pjsip_uri*)uri)->vptr->p_get_scheme)(uri);
-}
-
-/**
- * Generic function to get the URI object contained by this URI, or the URI
- * itself if it doesn't contain another URI.
- *
- * @param uri the URI.
- * @return the URI.
- */
-PJ_INLINE(void*) pjsip_uri_get_uri(void *uri)
-{
- return (*((pjsip_uri*)uri)->vptr->p_get_uri)(uri);
-}
-
-/**
- * Generic function to compare two URIs.
- *
- * @param context Comparison context.
- * @param uri1 The first URI.
- * @param uri2 The second URI.
- * @return PJ_SUCCESS if equal, or otherwise the error status which
- * should point to the mismatch part.
- */
-PJ_INLINE(pj_status_t) pjsip_uri_cmp(pjsip_uri_context_e context,
- const void *uri1, const void *uri2)
-{
- return (*((const pjsip_uri*)uri1)->vptr->p_compare)(context, uri1, uri2);
-}
-
-/**
- * Generic function to print an URI object.
- *
- * @param context Print context.
- * @param uri The URI to print.
- * @param buf The buffer.
- * @param size Size of the buffer.
- * @return Length printed.
- */
-PJ_INLINE(int) pjsip_uri_print(pjsip_uri_context_e context,
- const void *uri,
- char *buf, pj_size_t size)
-{
- return (*((const pjsip_uri*)uri)->vptr->p_print)(context, uri, buf, size);
-}
-
-/**
- * Generic function to clone an URI object.
- *
- * @param pool Pool.
- * @param uri URI to clone.
- * @return New URI.
- */
-PJ_INLINE(void*) pjsip_uri_clone( pj_pool_t *pool, const void *uri )
-{
- return (*((const pjsip_uri*)uri)->vptr->p_clone)(pool, uri);
-}
-
-
-/**
- * Create new SIP URL and initialize all fields with zero or NULL.
- * @param pool The pool.
- * @param secure Tlag to indicate whether secure transport should be used.
- * @return SIP URL.
- */
-PJ_DECL(pjsip_url*) pjsip_url_create( pj_pool_t *pool, int secure );
-
-/**
- * Create new SIPS URL and initialize all fields with zero or NULL.
- * @param pool The pool.
- * @return SIPS URL.
- */
-PJ_DECL(pjsip_url*) pjsips_url_create( pj_pool_t *pool );
-
-/**
- * Initialize SIP URL (all fields are set to NULL or zero).
- * @param url The URL.
- */
-PJ_DECL(void) pjsip_url_init(pjsip_url *url, int secure);
-
-/**
- * Perform full assignment to the SIP URL.
- * @param pool The pool.
- * @param url Destination URL.
- * @param rhs The source URL.
- */
-PJ_DECL(void) pjsip_url_assign(pj_pool_t *pool, pjsip_url *url, const pjsip_url *rhs);
-
-/**
- * Create new instance of name address and initialize all fields with zero or
- * NULL.
- * @param pool The pool.
- * @return New SIP name address.
- */
-PJ_DECL(pjsip_name_addr*) pjsip_name_addr_create(pj_pool_t *pool);
-
-/**
- * Initialize with default value.
- * @param name_addr The name address.
- */
-PJ_DECL(void) pjsip_name_addr_init(pjsip_name_addr *name_addr);
-
-/**
- * Perform full assignment to the name address.
- * @param pool The pool.
- * @param addr The destination name address.
- * @param rhs The source name address.
- */
-PJ_DECL(void) pjsip_name_addr_assign(pj_pool_t *pool,
- pjsip_name_addr *addr,
- const pjsip_name_addr *rhs);
-
-
-
-
-/**
- * @}
- */
-
-PJ_END_DECL
-
-#endif /* __PJSIP_URL_H__ */
-
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIP_URI_H__ +#define __PJSIP_SIP_URI_H__ + +/** + * @file sip_uri.h + * @brief SIP URL Structures and Manipulations + */ + +#include <pjsip/sip_types.h> +#include <pjsip/sip_config.h> +#include <pj/list.h> + +PJ_BEGIN_DECL + + +/** + * @defgroup PJSIP_URL URL Structures + * @brief SIP Url, tel: Url, and generic URI. + * @ingroup PJSIP_MSG + * @{ + */ + +/** + * Generic parameter, normally used in other_param or header_param. + */ +typedef struct pjsip_param +{ + PJ_DECL_LIST_MEMBER(struct pjsip_param); /**< Generic list member. */ + pj_str_t name; /**< Param/header name. */ + pj_str_t value; /**< Param/header value. */ +} pjsip_param; + + +/** + * Find the specified parameter name in the list. The name will be compared + * in case-insensitive comparison. + * + * @param param_list List of parameters to find. + * @param name Parameter/header name to find. + * + * @return The parameter if found, or NULL. + */ +PJ_DECL(pjsip_param*) pjsip_param_find( pjsip_param *param_list, + const pj_str_t *name ); + + +/** + * Find the specified parameter name in the list. The name will be compared + * in case-insensitive comparison. + * + * @param param_list List of parameters to find. + * @param name Parameter/header name to find. + * + * @return The parameter if found, or NULL. + */ +PJ_DECL(const pjsip_param*) pjsip_param_cfind(const pjsip_param *param_list, + const pj_str_t *name ); + + +/** + * Duplicate the parameters. + * + * @param pool Pool to allocate memory from. + * @param dst_list Destination list. + * @param src_list Source list. + */ +PJ_DECL(void) pjsip_param_clone(pj_pool_t *pool, pjsip_param *dst_list, + const pjsip_param *src_list); + +/** + * Duplicate the parameters. + * + * @param pool Pool to allocate memory from. + * @param dst_list Destination list. + * @param src_list Source list. + */ +PJ_DECL(void) pjsip_param_shallow_clone(pj_pool_t *pool, + pjsip_param *dst_list, + const pjsip_param *src_list); + +/** + * Print parameters. + * + * @param param_list The parameter list. + * @param buf Buffer. + * @param size Size of buffer. + * @param sep Separator character (either ';' or ','). + * + * @return The number of bytes printed, or -1 on errr. + */ +PJ_DECL(pj_ssize_t) pjsip_param_print_on(const pjsip_param *param_list, + char *buf, pj_size_t size, + int sep); + +/** + * URI context. + */ +typedef enum pjsip_uri_context_e +{ + PJSIP_URI_IN_REQ_URI, /**< The URI is in Request URI. */ + PJSIP_URI_IN_FROMTO_HDR, /**< The URI is in From/To header. */ + PJSIP_URI_IN_CONTACT_HDR, /**< The URI is in Contact header. */ + PJSIP_URI_IN_ROUTING_HDR, /**< The URI is in Route/Record-Route header. */ + PJSIP_URI_IN_OTHER, /**< Other context (web page, business card, etc.) */ +} pjsip_uri_context_e; + +/** + * URI 'virtual' function table. + * All types of URI in this library (such as sip:, sips:, tel:, and name-addr) + * will have pointer to this table as their first struct member. This table + * provides polimorphic behaviour to the URI. + */ +typedef struct pjsip_uri_vptr +{ + /** + * Get URI scheme. + * @param uri the URI (self). + * @return the URI scheme. + */ + const pj_str_t* (*p_get_scheme)(const void *uri); + + /** + * Get the URI object contained by this URI, or the URI itself if + * it doesn't contain another URI. + * @param uri the URI (self). + */ + void* (*p_get_uri)(void *uri); + + /** + * Print URI components to the buffer, following the rule of which + * components are allowed for the context. + * @param context the context where the URI will be placed. + * @param uri the URI (self). + * @param buf the buffer. + * @param size the size of the buffer. + * @return the length printed. + */ + int (*p_print)(pjsip_uri_context_e context, + const void *uri, + char *buf, pj_size_t size); + + /** + * Compare two URIs according to the context. + * @param context the context. + * @param uri1 the first URI (self). + * @param uri2 the second URI. + * @return PJ_SUCCESS if equal, or otherwise the error status which + * should point to the mismatch part. + */ + pj_status_t (*p_compare)(pjsip_uri_context_e context, + const void *uri1, const void *uri2); + + /** + * Clone URI. + * @param pool the pool. + * @param the URI to clone (self). + * @return new URI. + */ + void *(*p_clone)(pj_pool_t *pool, const void *uri); + +} pjsip_uri_vptr; + + +/** + * The declaration of 'base class' for all URI scheme. + */ +struct pjsip_uri +{ + /** All URIs must have URI virtual function table as their first member. */ + pjsip_uri_vptr *vptr; +}; + +/** + * This macro checks that the URL is a "sip:" or "sips:" URL. + * @param url The URL (pointer to) + * @return non-zero if TRUE. + */ +#define PJSIP_URI_SCHEME_IS_SIP(url) \ + (pj_strnicmp2(pjsip_uri_get_scheme(url), "sip", 3)==0) + +/** + * This macro checks that the URL is a "sips:" URL (not SIP). + * @param url The URL (pointer to) + * @return non-zero if TRUE. + */ +#define PJSIP_URI_SCHEME_IS_SIPS(url) \ + (pj_strnicmp2(pjsip_uri_get_scheme(url), "sips", 4)==0) + +/** + * This macro checks that the URL is a "tel:" URL. + * @param url The URL (pointer to) + * @return non-zero if TRUE. + */ +#define PJSIP_URI_SCHEME_IS_TEL(url) \ + (pj_strnicmp2(pjsip_uri_get_scheme(url), "tel", 3)==0) + + +/** + * SIP and SIPS URL scheme. + */ +typedef struct pjsip_url +{ + pjsip_uri_vptr *vptr; /**< Pointer to virtual function table.*/ + pj_str_t user; /**< Optional user part. */ + pj_str_t passwd; /**< Optional password part. */ + pj_str_t host; /**< Host part, always exists. */ + int port; /**< Optional port number, or zero. */ + pj_str_t user_param; /**< Optional user parameter */ + pj_str_t method_param; /**< Optional method parameter. */ + pj_str_t transport_param; /**< Optional transport parameter. */ + int ttl_param; /**< Optional TTL param, or -1. */ + int lr_param; /**< Optional loose routing param, or zero */ + pj_str_t maddr_param; /**< Optional maddr param */ + pjsip_param other_param; /**< Other parameters grouped together. */ + pjsip_param header_param; /**< Optional header parameter. */ +} pjsip_url; + + +/** + * SIP name-addr, which typically appear in From, To, and Contact header. + * The SIP name-addr contains a generic URI and a display name. + */ +typedef struct pjsip_name_addr +{ + /** Pointer to virtual function table. */ + pjsip_uri_vptr *vptr; + + /** Optional display name. */ + pj_str_t display; + + /** URI part. */ + pjsip_uri *uri; + +} pjsip_name_addr; + + +/** + * Generic function to get the URI scheme. + * @param uri the URI object. + * @return the URI scheme. + */ +PJ_INLINE(const pj_str_t*) pjsip_uri_get_scheme(const void *uri) +{ + return (*((pjsip_uri*)uri)->vptr->p_get_scheme)(uri); +} + +/** + * Generic function to get the URI object contained by this URI, or the URI + * itself if it doesn't contain another URI. + * + * @param uri the URI. + * @return the URI. + */ +PJ_INLINE(void*) pjsip_uri_get_uri(void *uri) +{ + return (*((pjsip_uri*)uri)->vptr->p_get_uri)(uri); +} + +/** + * Generic function to compare two URIs. + * + * @param context Comparison context. + * @param uri1 The first URI. + * @param uri2 The second URI. + * @return PJ_SUCCESS if equal, or otherwise the error status which + * should point to the mismatch part. + */ +PJ_INLINE(pj_status_t) pjsip_uri_cmp(pjsip_uri_context_e context, + const void *uri1, const void *uri2) +{ + return (*((const pjsip_uri*)uri1)->vptr->p_compare)(context, uri1, uri2); +} + +/** + * Generic function to print an URI object. + * + * @param context Print context. + * @param uri The URI to print. + * @param buf The buffer. + * @param size Size of the buffer. + * @return Length printed. + */ +PJ_INLINE(int) pjsip_uri_print(pjsip_uri_context_e context, + const void *uri, + char *buf, pj_size_t size) +{ + return (*((const pjsip_uri*)uri)->vptr->p_print)(context, uri, buf, size); +} + +/** + * Generic function to clone an URI object. + * + * @param pool Pool. + * @param uri URI to clone. + * @return New URI. + */ +PJ_INLINE(void*) pjsip_uri_clone( pj_pool_t *pool, const void *uri ) +{ + return (*((const pjsip_uri*)uri)->vptr->p_clone)(pool, uri); +} + + +/** + * Create new SIP URL and initialize all fields with zero or NULL. + * @param pool The pool. + * @param secure Tlag to indicate whether secure transport should be used. + * @return SIP URL. + */ +PJ_DECL(pjsip_url*) pjsip_url_create( pj_pool_t *pool, int secure ); + +/** + * Create new SIPS URL and initialize all fields with zero or NULL. + * @param pool The pool. + * @return SIPS URL. + */ +PJ_DECL(pjsip_url*) pjsips_url_create( pj_pool_t *pool ); + +/** + * Initialize SIP URL (all fields are set to NULL or zero). + * @param url The URL. + */ +PJ_DECL(void) pjsip_url_init(pjsip_url *url, int secure); + +/** + * Perform full assignment to the SIP URL. + * @param pool The pool. + * @param url Destination URL. + * @param rhs The source URL. + */ +PJ_DECL(void) pjsip_url_assign(pj_pool_t *pool, pjsip_url *url, const pjsip_url *rhs); + +/** + * Create new instance of name address and initialize all fields with zero or + * NULL. + * @param pool The pool. + * @return New SIP name address. + */ +PJ_DECL(pjsip_name_addr*) pjsip_name_addr_create(pj_pool_t *pool); + +/** + * Initialize with default value. + * @param name_addr The name address. + */ +PJ_DECL(void) pjsip_name_addr_init(pjsip_name_addr *name_addr); + +/** + * Perform full assignment to the name address. + * @param pool The pool. + * @param addr The destination name address. + * @param rhs The source name address. + */ +PJ_DECL(void) pjsip_name_addr_assign(pj_pool_t *pool, + pjsip_name_addr *addr, + const pjsip_name_addr *rhs); + + + + +/** + * @} + */ + +PJ_END_DECL + +#endif /* __PJSIP_URL_H__ */ + diff --git a/pjsip/include/pjsip/sip_util.h b/pjsip/include/pjsip/sip_util.h index f8685e54..e158212a 100644 --- a/pjsip/include/pjsip/sip_util.h +++ b/pjsip/include/pjsip/sip_util.h @@ -1,192 +1,192 @@ -/* $Id$ */
-/*
- * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-#ifndef __PJSIP_SIP_MISC_H__
-#define __PJSIP_SIP_MISC_H__
-
-#include <pjsip/sip_msg.h>
-
-PJ_BEGIN_DECL
-
-/**
- * @defgroup PJSIP_ENDPT SIP Endpoint
- * @ingroup PJSIP
- * @{
- */
-
-/**
- * Create an independent request message. This can be used to build any
- * request outside a dialog, such as OPTIONS, MESSAGE, etc. To create a request
- * inside a dialog, application should use #pjsip_dlg_create_request.
- *
- * Once a transmit data is created, the reference counter is initialized to 1.
- *
- * @param endpt Endpoint instance.
- * @param method SIP Method.
- * @param target Target URI.
- * @param from URL to put in From header.
- * @param to URL to put in To header.
- * @param contact URL to put in Contact header.
- * @param call_id Optional Call-ID (put NULL to generate unique Call-ID).
- * @param cseq Optional CSeq (put -1 to generate random CSeq).
- * @param text Optional text body (put NULL to omit body).
- * @param p_tdata Pointer to receive the transmit data.
- *
- * @return PJ_SUCCESS, or the appropriate error code.
- */
-PJ_DECL(pj_status_t) pjsip_endpt_create_request( pjsip_endpoint *endpt,
- const pjsip_method *method,
- const pj_str_t *target,
- const pj_str_t *from,
- const pj_str_t *to,
- const pj_str_t *contact,
- const pj_str_t *call_id,
- int cseq,
- const pj_str_t *text,
- pjsip_tx_data **p_tdata);
-
-/**
- * Create an independent request message from the specified headers. This
- * function will shallow clone the headers and put them in the request.
- *
- * Once a transmit data is created, the reference counter is initialized to 1.
- *
- * @param endpt Endpoint instance.
- * @param method SIP Method.
- * @param target Target URI.
- * @param from URL to put in From header.
- * @param to URL to put in To header.
- * @param contact URL to put in Contact header.
- * @param call_id Optional Call-ID (put NULL to generate unique Call-ID).
- * @param cseq Optional CSeq (put -1 to generate random CSeq).
- * @param text Optional text body (put NULL to omit body).
- * @param p_tdata Pointer to receive the transmit data.
- *
- * @return PJ_SUCCESS, or the appropriate error code.
- */
-PJ_DECL(pj_status_t)
-pjsip_endpt_create_request_from_hdr( pjsip_endpoint *endpt,
- const pjsip_method *method,
- const pjsip_uri *target,
- const pjsip_from_hdr *from,
- const pjsip_to_hdr *to,
- const pjsip_contact_hdr *contact,
- const pjsip_cid_hdr *call_id,
- int cseq,
- const pj_str_t *text,
- pjsip_tx_data **p_tdata);
-
-/**
- * Send outgoing request and initiate UAC transaction for the request.
- * This is an auxiliary function to be used by application to send arbitrary
- * requests outside a dialog. To send a request within a dialog, application
- * should use #pjsip_dlg_send_msg instead.
- *
- * @param endpt The endpoint instance.
- * @param tdata The transmit data to be sent.
- * @param timeout Optional timeout for final response to be received, or -1
- * if the transaction should not have a timeout restriction.
- * @param token Optional token to be associated with the transaction, and
- * to be passed to the callback.
- * @param cb Optional callback to be called when the transaction has
- * received a final response. The callback will be called with
- * the previously registered token and the event that triggers
- * the completion of the transaction.
- *
- * @return PJ_SUCCESS, or the appropriate error code.
- */
-PJ_DECL(pj_status_t) pjsip_endpt_send_request( pjsip_endpoint *endpt,
- pjsip_tx_data *tdata,
- int timeout,
- void *token,
- void (*cb)(void*,pjsip_event*));
-
-/**
- * Construct a minimal response message for the received request. This function
- * will construct all the Via, Record-Route, Call-ID, From, To, CSeq, and
- * Call-ID headers from the request.
- *
- * Note: the txdata reference counter is set to ZERO!.
- *
- * @param endpt The endpoint.
- * @param rdata The request receive data.
- * @param code Status code to be put in the response.
- * @param p_tdata Pointer to receive the transmit data.
- *
- * @return PJ_SUCCESS, or the appropriate error code.
- */
-PJ_DECL(pj_status_t) pjsip_endpt_create_response( pjsip_endpoint *endpt,
- const pjsip_rx_data *rdata,
- int code,
- pjsip_tx_data **p_tdata);
-
-/**
- * Construct a full ACK request for the received non-2xx final response.
- * This utility function is normally called by the transaction to construct
- * an ACK request to 3xx-6xx final response.
- * The generation of ACK message for 2xx final response is different than
- * this one.
- *
- * @param endpt The endpoint.
- * @param tdata On input, this contains the original INVITE request, and on
- * output, it contains the ACK message.
- * @param rdata The final response message.
- */
-PJ_DECL(void) pjsip_endpt_create_ack( pjsip_endpoint *endpt,
- pjsip_tx_data *tdata,
- const pjsip_rx_data *rdata );
-
-
-/**
- * Construct CANCEL request for the previously sent request.
- *
- * @param endpt The endpoint.
- * @param tdata The transmit buffer for the request being cancelled.
- * @param p_tdata Pointer to receive the transmit data.
- *
- * @return PJ_SUCCESS, or the appropriate error code.
- */
-PJ_DECL(pj_status_t) pjsip_endpt_create_cancel( pjsip_endpoint *endpt,
- pjsip_tx_data *tdata,
- pjsip_tx_data **p_tdata);
-
-
-/**
- * Get the address parameters (host, port, flag, TTL, etc) to send the
- * response.
- *
- * @param pool The pool.
- * @param tr The transport where the request was received.
- * @param via The top-most Via header of the request.
- * @param addr The send address concluded from the calculation.
- *
- * @return zero (PJ_OK) if successfull.
- */
-PJ_DECL(pj_status_t) pjsip_get_response_addr(pj_pool_t *pool,
- const pjsip_transport *tr,
- const pjsip_via_hdr *via,
- pjsip_host_port *addr);
-
-/**
- * @}
- */
-
-PJ_END_DECL
-
-#endif /* __PJSIP_SIP_MISC_H__ */
-
+/* $Id$ */ +/* + * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ +#ifndef __PJSIP_SIP_MISC_H__ +#define __PJSIP_SIP_MISC_H__ + +#include <pjsip/sip_msg.h> + +PJ_BEGIN_DECL + +/** + * @defgroup PJSIP_ENDPT SIP Endpoint + * @ingroup PJSIP + * @{ + */ + +/** + * Create an independent request message. This can be used to build any + * request outside a dialog, such as OPTIONS, MESSAGE, etc. To create a request + * inside a dialog, application should use #pjsip_dlg_create_request. + * + * Once a transmit data is created, the reference counter is initialized to 1. + * + * @param endpt Endpoint instance. + * @param method SIP Method. + * @param target Target URI. + * @param from URL to put in From header. + * @param to URL to put in To header. + * @param contact URL to put in Contact header. + * @param call_id Optional Call-ID (put NULL to generate unique Call-ID). + * @param cseq Optional CSeq (put -1 to generate random CSeq). + * @param text Optional text body (put NULL to omit body). + * @param p_tdata Pointer to receive the transmit data. + * + * @return PJ_SUCCESS, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsip_endpt_create_request( pjsip_endpoint *endpt, + const pjsip_method *method, + const pj_str_t *target, + const pj_str_t *from, + const pj_str_t *to, + const pj_str_t *contact, + const pj_str_t *call_id, + int cseq, + const pj_str_t *text, + pjsip_tx_data **p_tdata); + +/** + * Create an independent request message from the specified headers. This + * function will shallow clone the headers and put them in the request. + * + * Once a transmit data is created, the reference counter is initialized to 1. + * + * @param endpt Endpoint instance. + * @param method SIP Method. + * @param target Target URI. + * @param from URL to put in From header. + * @param to URL to put in To header. + * @param contact URL to put in Contact header. + * @param call_id Optional Call-ID (put NULL to generate unique Call-ID). + * @param cseq Optional CSeq (put -1 to generate random CSeq). + * @param text Optional text body (put NULL to omit body). + * @param p_tdata Pointer to receive the transmit data. + * + * @return PJ_SUCCESS, or the appropriate error code. + */ +PJ_DECL(pj_status_t) +pjsip_endpt_create_request_from_hdr( pjsip_endpoint *endpt, + const pjsip_method *method, + const pjsip_uri *target, + const pjsip_from_hdr *from, + const pjsip_to_hdr *to, + const pjsip_contact_hdr *contact, + const pjsip_cid_hdr *call_id, + int cseq, + const pj_str_t *text, + pjsip_tx_data **p_tdata); + +/** + * Send outgoing request and initiate UAC transaction for the request. + * This is an auxiliary function to be used by application to send arbitrary + * requests outside a dialog. To send a request within a dialog, application + * should use #pjsip_dlg_send_msg instead. + * + * @param endpt The endpoint instance. + * @param tdata The transmit data to be sent. + * @param timeout Optional timeout for final response to be received, or -1 + * if the transaction should not have a timeout restriction. + * @param token Optional token to be associated with the transaction, and + * to be passed to the callback. + * @param cb Optional callback to be called when the transaction has + * received a final response. The callback will be called with + * the previously registered token and the event that triggers + * the completion of the transaction. + * + * @return PJ_SUCCESS, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsip_endpt_send_request( pjsip_endpoint *endpt, + pjsip_tx_data *tdata, + int timeout, + void *token, + void (*cb)(void*,pjsip_event*)); + +/** + * Construct a minimal response message for the received request. This function + * will construct all the Via, Record-Route, Call-ID, From, To, CSeq, and + * Call-ID headers from the request. + * + * Note: the txdata reference counter is set to ZERO!. + * + * @param endpt The endpoint. + * @param rdata The request receive data. + * @param code Status code to be put in the response. + * @param p_tdata Pointer to receive the transmit data. + * + * @return PJ_SUCCESS, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsip_endpt_create_response( pjsip_endpoint *endpt, + const pjsip_rx_data *rdata, + int code, + pjsip_tx_data **p_tdata); + +/** + * Construct a full ACK request for the received non-2xx final response. + * This utility function is normally called by the transaction to construct + * an ACK request to 3xx-6xx final response. + * The generation of ACK message for 2xx final response is different than + * this one. + * + * @param endpt The endpoint. + * @param tdata On input, this contains the original INVITE request, and on + * output, it contains the ACK message. + * @param rdata The final response message. + */ +PJ_DECL(void) pjsip_endpt_create_ack( pjsip_endpoint *endpt, + pjsip_tx_data *tdata, + const pjsip_rx_data *rdata ); + + +/** + * Construct CANCEL request for the previously sent request. + * + * @param endpt The endpoint. + * @param tdata The transmit buffer for the request being cancelled. + * @param p_tdata Pointer to receive the transmit data. + * + * @return PJ_SUCCESS, or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsip_endpt_create_cancel( pjsip_endpoint *endpt, + pjsip_tx_data *tdata, + pjsip_tx_data **p_tdata); + + +/** + * Get the address parameters (host, port, flag, TTL, etc) to send the + * response. + * + * @param pool The pool. + * @param tr The transport where the request was received. + * @param via The top-most Via header of the request. + * @param addr The send address concluded from the calculation. + * + * @return zero (PJ_OK) if successfull. + */ +PJ_DECL(pj_status_t) pjsip_get_response_addr(pj_pool_t *pool, + const pjsip_transport *tr, + const pjsip_via_hdr *via, + pjsip_host_port *addr); + +/** + * @} + */ + +PJ_END_DECL + +#endif /* __PJSIP_SIP_MISC_H__ */ + |