res_pjsip_session.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2013, Digium, Inc.
00005  *
00006  * Mark Michelson <mmichelson@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 #ifndef _RES_PJSIP_SESSION_H
00020 #define _RES_PJSIP_SESSION_H
00021 
00022 /* Needed for pj_timer_entry definition */
00023 #include "pjlib.h"
00024 #include "asterisk/linkedlists.h"
00025 /* Needed for AST_MAX_EXTENSION constant */
00026 #include "asterisk/channel.h"
00027 /* Needed for ast_sockaddr struct */
00028 #include "asterisk/netsock2.h"
00029 /* Needed for ast_sdp_srtp struct */
00030 #include "asterisk/sdp_srtp.h"
00031 
00032 /* Forward declarations */
00033 struct ast_sip_endpoint;
00034 struct ast_sip_transport;
00035 struct pjsip_inv_session;
00036 struct ast_channel;
00037 struct ast_datastore;
00038 struct ast_datastore_info;
00039 struct ao2_container;
00040 struct pjsip_tx_data;
00041 struct pjsip_rx_data;
00042 struct ast_party_id;
00043 struct pjmedia_sdp_media;
00044 struct pjmedia_sdp_session;
00045 struct ast_dsp;
00046 struct ast_udptl;
00047 
00048 /*! \brief T.38 states for a session */
00049 enum ast_sip_session_t38state {
00050    T38_DISABLED = 0,   /*!< Not enabled */
00051    T38_LOCAL_REINVITE, /*!< Offered from local - REINVITE */
00052    T38_PEER_REINVITE,  /*!< Offered from peer - REINVITE */
00053    T38_ENABLED,        /*!< Negotiated (enabled) */
00054    T38_REJECTED,       /*!< Refused */
00055    T38_MAX_ENUM,       /*!< Not an actual state; used as max value in the enum */
00056 };
00057 
00058 struct ast_sip_session_sdp_handler;
00059 
00060 /*!
00061  * \brief A structure containing SIP session media information
00062  */
00063 struct ast_sip_session_media {
00064    union {
00065       /*! \brief RTP instance itself */
00066       struct ast_rtp_instance *rtp;
00067       /*! \brief UDPTL instance itself */
00068       struct ast_udptl *udptl;
00069    };
00070    /*! \brief Direct media address */
00071    struct ast_sockaddr direct_media_addr;
00072    /*! \brief SDP handler that setup the RTP */
00073    struct ast_sip_session_sdp_handler *handler;
00074    /*! \brief Holds SRTP information */
00075    struct ast_sdp_srtp *srtp;
00076    /*! \brief What type of encryption is in use on this stream */
00077    enum ast_sip_session_media_encryption encryption;
00078    /*! \brief The media transport in use for this stream */
00079    pj_str_t transport;
00080    /*! \brief Stream is on hold by remote side */
00081    unsigned int remotely_held:1;
00082    /*! \brief Stream is on hold by local side */
00083    unsigned int locally_held:1;
00084    /*! \brief Stream type this session media handles */
00085    char stream_type[1];
00086 };
00087 
00088 /*!
00089  * \brief Opaque structure representing a request that could not be sent
00090  * due to an outstanding INVITE transaction
00091  */
00092 struct ast_sip_session_delayed_request;
00093 
00094 /*! \brief Opaque struct controlling the suspension of the session's serializer. */
00095 struct ast_sip_session_suspender;
00096 
00097 /*!
00098  * \brief A structure describing a SIP session
00099  *
00100  * For the sake of brevity, a "SIP session" in Asterisk is referring to
00101  * a dialog initiated by an INVITE. While "session" is typically interpreted
00102  * to refer to the negotiated media within a SIP dialog, we have opted
00103  * to use the term "SIP session" to refer to the INVITE dialog itself.
00104  */
00105 struct ast_sip_session {
00106    /*! Dialplan extension where incoming call is destined */
00107    char exten[AST_MAX_EXTENSION];
00108    /*! The endpoint with which Asterisk is communicating */
00109    struct ast_sip_endpoint *endpoint;
00110    /*! The contact associated with this session */
00111    struct ast_sip_contact *contact;
00112    /*! The PJSIP details of the session, which includes the dialog */
00113    struct pjsip_inv_session *inv_session;
00114    /*! The Asterisk channel associated with the session */
00115    struct ast_channel *channel;
00116    /*! Registered session supplements */
00117    AST_LIST_HEAD(, ast_sip_session_supplement) supplements;
00118    /*! Datastores added to the session by supplements to the session */
00119    struct ao2_container *datastores;
00120    /*! Media streams */
00121    struct ao2_container *media;
00122    /*! Serializer for tasks relating to this SIP session */
00123    struct ast_taskprocessor *serializer;
00124    /*! Non-null if the session serializer is suspended or being suspended. */
00125    struct ast_sip_session_suspender *suspended;
00126    /*! Requests that could not be sent due to current inv_session state */
00127    AST_LIST_HEAD_NOLOCK(, ast_sip_session_delayed_request) delayed_requests;
00128    /*! When we need to reschedule a reinvite, we use this structure to do it */
00129    pj_timer_entry rescheduled_reinvite;
00130    /*! Format capabilities pertaining to direct media */
00131    struct ast_format_cap *direct_media_cap;
00132    /*! When we need to forcefully end the session */
00133    pj_timer_entry scheduled_termination;
00134    /*! Identity of endpoint this session deals with */
00135    struct ast_party_id id;
00136    /*! Requested capabilities */
00137    struct ast_format_cap *req_caps;
00138    /*! Optional DSP, used only for inband DTMF detection if configured */
00139    struct ast_dsp *dsp;
00140    /*! Whether the termination of the session should be deferred */
00141    unsigned int defer_terminate:1;
00142    /*! Termination requested while termination deferred */
00143    unsigned int terminate_while_deferred:1;
00144    /*! Deferred incoming re-invite */
00145    pjsip_rx_data *deferred_reinvite;
00146    /*! Current T.38 state */
00147    enum ast_sip_session_t38state t38state;
00148    /*! The AOR associated with this session */
00149    struct ast_sip_aor *aor;
00150 };
00151 
00152 typedef int (*ast_sip_session_request_creation_cb)(struct ast_sip_session *session, pjsip_tx_data *tdata);
00153 typedef int (*ast_sip_session_response_cb)(struct ast_sip_session *session, pjsip_rx_data *rdata);
00154 typedef int (*ast_sip_session_sdp_creation_cb)(struct ast_sip_session *session, pjmedia_sdp_session *sdp);
00155 
00156 /*!
00157  * \brief Describes when a supplement should be called into on incoming responses.
00158  *
00159  * In most cases, session supplements will not need to worry about this because in most cases,
00160  * the correct value will be automatically applied. However, there are rare circumstances
00161  * when a supplement will want to specify when it should be called.
00162  *
00163  * The values below are listed in chronological order.
00164  */
00165 enum ast_sip_session_response_priority {
00166    /*!
00167     * When processing 3XX responses, the supplement is called into before
00168     * the redirecting information is processed.
00169     */
00170    AST_SIP_SESSION_BEFORE_REDIRECTING = (1 << 0),
00171    /*!
00172     * For responses to INVITE transactions, the supplement is called into
00173     * before media is negotiated.
00174     *
00175     * This priority is applied by default to any session supplement that
00176     * does not specify a response priority.
00177     */
00178    AST_SIP_SESSION_BEFORE_MEDIA = (1 << 1),
00179    /*!
00180     * For INVITE transactions, the supplement is called into after media
00181     * is negotiated.
00182     */
00183    AST_SIP_SESSION_AFTER_MEDIA = (1 << 2),
00184 };
00185 
00186 /*!
00187  * \brief A supplement to SIP message processing
00188  *
00189  * These can be registered by any module in order to add
00190  * processing to incoming and outgoing SIP requests and responses
00191  */
00192 struct ast_sip_session_supplement {
00193    /*! Method on which to call the callbacks. If NULL, call on all methods */
00194    const char *method;
00195    /*! Priority for this supplement. Lower numbers are visited before higher numbers */
00196    enum ast_sip_supplement_priority priority;
00197    /*!
00198     * \brief Notification that the session has begun
00199     * This method will always be called from a SIP servant thread.
00200     */
00201    void (*session_begin)(struct ast_sip_session *session);
00202    /*! 
00203     * \brief Notification that the session has ended
00204     *
00205     * This method may or may not be called from a SIP servant thread. Do
00206     * not make assumptions about being able to call PJSIP methods from within
00207     * this method.
00208     */
00209    void (*session_end)(struct ast_sip_session *session);
00210    /*!
00211     * \brief Notification that the session is being destroyed
00212     */
00213    void (*session_destroy)(struct ast_sip_session *session);
00214    /*!
00215     * \brief Called on incoming SIP request
00216     * This method can indicate a failure in processing in its return. If there
00217     * is a failure, it is required that this method sends a response to the request.
00218     * This method is always called from a SIP servant thread.
00219     *
00220     * \note
00221     * The following PJSIP methods will not work properly:
00222     * pjsip_rdata_get_dlg()
00223     * pjsip_rdata_get_tsx()
00224     * The reason is that the rdata passed into this function is a cloned rdata structure,
00225     * and its module data is not copied during the cloning operation.
00226     * If you need to get the dialog, you can get it via session->inv_session->dlg.
00227     *
00228     * \note
00229     * There is no guarantee that a channel will be present on the session when this is called.
00230     */
00231    int (*incoming_request)(struct ast_sip_session *session, struct pjsip_rx_data *rdata);
00232    /*! 
00233     * \brief Called on an incoming SIP response
00234     * This method is always called from a SIP servant thread.
00235     *
00236     * \note
00237     * The following PJSIP methods will not work properly:
00238     * pjsip_rdata_get_dlg()
00239     * pjsip_rdata_get_tsx()
00240     * The reason is that the rdata passed into this function is a cloned rdata structure,
00241     * and its module data is not copied during the cloning operation.
00242     * If you need to get the dialog, you can get it via session->inv_session->dlg.
00243     *
00244     * \note
00245     * There is no guarantee that a channel will be present on the session when this is called.
00246     */
00247    void (*incoming_response)(struct ast_sip_session *session, struct pjsip_rx_data *rdata);
00248    /*!
00249     * \brief Called on an outgoing SIP request
00250     * This method is always called from a SIP servant thread.
00251     */
00252    void (*outgoing_request)(struct ast_sip_session *session, struct pjsip_tx_data *tdata);
00253    /*! 
00254     * \brief Called on an outgoing SIP response
00255     * This method is always called from a SIP servant thread.
00256     */
00257    void (*outgoing_response)(struct ast_sip_session *session, struct pjsip_tx_data *tdata);
00258    /*! Next item in the list */
00259    AST_LIST_ENTRY(ast_sip_session_supplement) next;
00260    /*!
00261     * Determines when the supplement is processed when handling a response.
00262     * Defaults to AST_SIP_SESSION_BEFORE_MEDIA
00263     */
00264    enum ast_sip_session_response_priority response_priority;
00265 };
00266 
00267 enum ast_sip_session_sdp_stream_defer {
00268    /*! The stream was not handled by this handler. If there are other registered handlers for this stream type, they will be called. */
00269    AST_SIP_SESSION_SDP_DEFER_NOT_HANDLED,
00270    /*! There was an error encountered. No further operations will take place and the current negotiation will be abandoned. */
00271    AST_SIP_SESSION_SDP_DEFER_ERROR,
00272    /*! Re-invite is not needed */
00273    AST_SIP_SESSION_SDP_DEFER_NOT_NEEDED,
00274    /*! Re-invite should be deferred and will be resumed later. No further operations will take place. */
00275    AST_SIP_SESSION_SDP_DEFER_NEEDED,
00276 };
00277 
00278 /*!
00279  * \brief A handler for SDPs in SIP sessions
00280  *
00281  * An SDP handler is registered by a module that is interested in being the
00282  * responsible party for specific types of SDP streams.
00283  */
00284 struct ast_sip_session_sdp_handler {
00285    /*! An identifier for this handler */
00286    const char *id;
00287    /*!
00288     * \brief Determine whether a stream requires that the re-invite be deferred.
00289     * If a stream can not be immediately negotiated the re-invite can be deferred and
00290     * resumed at a later time. It is up to the handler which caused deferral to occur
00291     * to resume it.
00292     *
00293     * \param session The session for which the media is being re-invited
00294     * \param session_media The media being reinvited
00295     * \param sdp The entire SDP. Useful for getting "global" information, such as connections or attributes
00296     * \param stream PJSIP incoming SDP media lines to parse by handler.
00297     *
00298     * \return enum ast_sip_session_defer_stream
00299     *
00300     * \note This is optional, if not implemented the stream is assumed to not be deferred.
00301     */
00302    enum ast_sip_session_sdp_stream_defer (*defer_incoming_sdp_stream)(struct ast_sip_session *session, struct ast_sip_session_media *session_media, const struct pjmedia_sdp_session *sdp, const struct pjmedia_sdp_media *stream);
00303    /*!
00304     * \brief Set session details based on a stream in an incoming SDP offer or answer
00305     * \param session The session for which the media is being negotiated
00306     * \param session_media The media to be setup for this session
00307     * \param sdp The entire SDP. Useful for getting "global" information, such as connections or attributes
00308     * \param stream The stream on which to operate
00309     * \retval 0 The stream was not handled by this handler. If there are other registered handlers for this stream type, they will be called.
00310     * \retval <0 There was an error encountered. No further operation will take place and the current negotiation will be abandoned.
00311     * \retval >0 The stream was handled by this handler. No further handler of this stream type will be called.
00312     */
00313    int (*negotiate_incoming_sdp_stream)(struct ast_sip_session *session, struct ast_sip_session_media *session_media, const struct pjmedia_sdp_session *sdp, const struct pjmedia_sdp_media *stream);
00314    /*!
00315     * \brief Create an SDP media stream and add it to the outgoing SDP offer or answer
00316     * \param session The session for which media is being added
00317     * \param session_media The media to be setup for this session
00318     * \param stream The stream on which to operate
00319     * \retval 0 The stream was not handled by this handler. If there are other registered handlers for this stream type, they will be called.
00320     * \retval <0 There was an error encountered. No further operation will take place and the current negotiation will be abandoned.
00321     * \retval >0 The stream was handled by this handler. No further handler of this stream type will be called.
00322     */
00323    int (*handle_incoming_sdp_stream)(struct ast_sip_session *session, struct ast_sip_session_media *session_media, const struct pjmedia_sdp_session *sdp, struct pjmedia_sdp_media *stream);
00324    /*!
00325     * \brief Create an SDP media stream and add it to the outgoing SDP offer or answer
00326     * \param session The session for which media is being added
00327     * \param session_media The media to be setup for this session
00328     * \param sdp The entire SDP as currently built
00329     * \retval 0 This handler has no stream to add. If there are other registered handlers for this stream type, they will be called.
00330     * \retval <0 There was an error encountered. No further operation will take place and the current SDP negotiation will be abandoned.
00331     * \retval >0 The handler has a stream to be added to the SDP. No further handler of this stream type will be called.
00332     */
00333    int (*create_outgoing_sdp_stream)(struct ast_sip_session *session, struct ast_sip_session_media *session_media, struct pjmedia_sdp_session *sdp);
00334    /*!
00335     * \brief Update media stream with external address if applicable
00336     * \param tdata The outgoing message itself
00337     * \param stream The stream on which to operate
00338     * \param transport The transport the SDP is going out on
00339     */
00340    void (*change_outgoing_sdp_stream_media_address)(struct pjsip_tx_data *tdata, struct pjmedia_sdp_media *stream, struct ast_sip_transport *transport);
00341    /*!
00342     * \brief Apply a negotiated SDP media stream
00343     * \param session The session for which media is being applied
00344     * \param session_media The media to be setup for this session
00345     * \param local The entire local negotiated SDP
00346     * \param local_stream The local stream which to apply
00347     * \param remote The entire remote negotiated SDP
00348     * \param remote_stream The remote stream which to apply
00349     * \retval 0 The stream was not applied by this handler. If there are other registered handlers for this stream type, they will be called.
00350     * \retval <0 There was an error encountered. No further operation will take place and the current application will be abandoned.
00351     * \retval >0 The stream was handled by this handler. No further handler of this stream type will be called.
00352     */
00353    int (*apply_negotiated_sdp_stream)(struct ast_sip_session *session, struct ast_sip_session_media *session_media, const struct pjmedia_sdp_session *local, const struct pjmedia_sdp_media *local_stream,
00354       const struct pjmedia_sdp_session *remote, const struct pjmedia_sdp_media *remote_stream);
00355    /*!
00356     * \brief Destroy a session_media created by this handler
00357     * \param session The session for which media is being destroyed
00358     * \param session_media The media to destroy
00359     */
00360    void (*stream_destroy)(struct ast_sip_session_media *session_media);
00361    /*! Next item in the list. */
00362    AST_LIST_ENTRY(ast_sip_session_sdp_handler) next;
00363 };
00364 
00365 /*!
00366  * \brief A structure which contains a channel implementation and session
00367  */
00368 struct ast_sip_channel_pvt {
00369    /*! \brief Pointer to channel specific implementation information, must be ao2 object */
00370    void *pvt;
00371    /*! \brief Pointer to session */
00372    struct ast_sip_session *session;
00373 };
00374 
00375 /*!
00376  * \brief Allocate a new SIP channel pvt structure
00377  *
00378  * \param pvt Pointer to channel specific implementation
00379  * \param session Pointer to SIP session
00380  *
00381  * \retval non-NULL success
00382  * \retval NULL failure
00383  */
00384 struct ast_sip_channel_pvt *ast_sip_channel_pvt_alloc(void *pvt, struct ast_sip_session *session);
00385 
00386 /*!
00387  * \brief Allocate a new SIP session
00388  *
00389  * This will take care of allocating the datastores container on the session as well
00390  * as placing all registered supplements onto the session.
00391  *
00392  * The endpoint that is passed in will have its reference count increased by one since
00393  * the session will be keeping a reference to the endpoint. The session will relinquish
00394  * this reference when the session is destroyed.
00395  *
00396  * \param endpoint The endpoint that this session communicates with
00397  * \param contact The contact associated with this session
00398  * \param inv_session The PJSIP INVITE session data
00399  */
00400 struct ast_sip_session *ast_sip_session_alloc(struct ast_sip_endpoint *endpoint,
00401    struct ast_sip_contact *contact, pjsip_inv_session *inv);
00402 
00403 /*!
00404  * \brief Request and wait for the session serializer to be suspended.
00405  * \since 12.7.0
00406  *
00407  * \param session Which session to suspend the serializer.
00408  *
00409  * \note No channel locks can be held while calling without risk of deadlock.
00410  *
00411  * \return Nothing
00412  */
00413 void ast_sip_session_suspend(struct ast_sip_session *session);
00414 
00415 /*!
00416  * \brief Request the session serializer be unsuspended.
00417  * \since 12.7.0
00418  *
00419  * \param session Which session to unsuspend the serializer.
00420  *
00421  * \return Nothing
00422  */
00423 void ast_sip_session_unsuspend(struct ast_sip_session *session);
00424 
00425 /*!
00426  * \brief Create a new outgoing SIP session
00427  *
00428  * The endpoint that is passed in will have its reference count increased by one since
00429  * the session will be keeping a reference to the endpoint. The session will relinquish
00430  * this reference when the session is destroyed.
00431  *
00432  * \param endpoint The endpoint that this session uses for settings
00433  * \param contact The contact that this session will communicate with
00434  * \param location Name of the location to call, be it named location or explicit URI. Overrides contact if present.
00435  * \param request_user Optional request user to place in the request URI if permitted
00436  * \param req_caps The requested capabilities
00437  */
00438 struct ast_sip_session *ast_sip_session_create_outgoing(struct ast_sip_endpoint *endpoint,
00439    struct ast_sip_contact *contact, const char *location, const char *request_user,
00440    struct ast_format_cap *req_caps);
00441 
00442 /*!
00443  * \brief Terminate a session and, if possible, send the provided response code
00444  *
00445  * \param session The session to terminate
00446  * \param response The response code to use for termination if possible
00447  */
00448 void ast_sip_session_terminate(struct ast_sip_session *session, int response);
00449 
00450 /*!
00451  * \brief Defer local termination of a session until remote side terminates, or an amount of time passes
00452  *
00453  * \param session The session to defer termination on
00454  *
00455  * \retval 0 Success
00456  * \retval -1 Failure
00457  */
00458 int ast_sip_session_defer_termination(struct ast_sip_session *session);
00459 
00460 /*!
00461  * \brief Cancel a pending deferred termination.
00462  *
00463  * \param session The session to cancel a deferred termination on.
00464  */
00465 void ast_sip_session_defer_termination_cancel(struct ast_sip_session *session);
00466 
00467 /*!
00468  * \brief Register an SDP handler
00469  *
00470  * An SDP handler is responsible for parsing incoming SDP streams and ensuring that
00471  * Asterisk can cope with the contents. Similarly, the SDP handler will be
00472  * responsible for constructing outgoing SDP streams.
00473  *
00474  * Multiple handlers for the same stream type may be registered. They will be
00475  * visited in the order they were registered. Handlers will be visited for each
00476  * stream type until one claims to have handled the stream.
00477  *
00478  * \param handler The SDP handler to register
00479  * \param stream_type The type of media stream for which to call the handler
00480  * \retval 0 Success
00481  * \retval -1 Failure
00482  */
00483 int ast_sip_session_register_sdp_handler(struct ast_sip_session_sdp_handler *handler, const char *stream_type);
00484 
00485 /*!
00486  * \brief Unregister an SDP handler
00487  *
00488  * \param handler The SDP handler to unregister
00489  * \param stream_type Stream type for which the SDP handler was registered
00490  */
00491 void ast_sip_session_unregister_sdp_handler(struct ast_sip_session_sdp_handler *handler, const char *stream_type);
00492 
00493 /*!
00494  * \brief Register a supplement to SIP session processing
00495  *
00496  * This allows for someone to insert themselves in the processing of SIP
00497  * requests and responses. This, for example could allow for a module to
00498  * set channel data based on headers in an incoming message. Similarly,
00499  * a module could reject an incoming request if desired.
00500  *
00501  * \param supplement The supplement to register
00502  * \retval 0 Success
00503  * \retval -1 Failure
00504  */
00505 int ast_sip_session_register_supplement(struct ast_sip_session_supplement *supplement);
00506 
00507 /*!
00508  * \brief Unregister a an supplement to SIP session processing
00509  *
00510  * \param supplement The supplement to unregister
00511  */
00512 void ast_sip_session_unregister_supplement(struct ast_sip_session_supplement *supplement);
00513 
00514 /*!
00515  * \brief Alternative for ast_datastore_alloc()
00516  *
00517  * There are two major differences between this and ast_datastore_alloc()
00518  * 1) This allocates a refcounted object
00519  * 2) This will fill in a uid if one is not provided
00520  *
00521  * DO NOT call ast_datastore_free() on a datastore allocated in this
00522  * way since that function will attempt to free the datastore rather
00523  * than play nicely with its refcount.
00524  *
00525  * \param info Callbacks for datastore
00526  * \param uid Identifier for datastore
00527  * \retval NULL Failed to allocate datastore
00528  * \retval non-NULL Newly allocated datastore
00529  */
00530 struct ast_datastore *ast_sip_session_alloc_datastore(const struct ast_datastore_info *info, const char *uid);
00531 
00532 /*!
00533  * \brief Add a datastore to a SIP session
00534  *
00535  * Note that SIP uses reference counted datastores. The datastore passed into this function
00536  * must have been allocated using ao2_alloc() or there will be serious problems.
00537  *
00538  * \param session The session to add the datastore to
00539  * \param datastore The datastore to be added to the session
00540  * \retval 0 Success
00541  * \retval -1 Failure
00542  */
00543 int ast_sip_session_add_datastore(struct ast_sip_session *session, struct ast_datastore *datastore);
00544 
00545 /*!
00546  * \brief Retrieve a session datastore
00547  *
00548  * The datastore retrieved will have its reference count incremented. When the caller is done
00549  * with the datastore, the reference counted needs to be decremented using ao2_ref().
00550  *
00551  * \param session The session from which to retrieve the datastore
00552  * \param name The name of the datastore to retrieve
00553  * \retval NULL Failed to find the specified datastore
00554  * \retval non-NULL The specified datastore
00555  */
00556 struct ast_datastore *ast_sip_session_get_datastore(struct ast_sip_session *session, const char *name);
00557 
00558 /*!
00559  * \brief Remove a session datastore from the session
00560  *
00561  * This operation may cause the datastore's free() callback to be called if the reference
00562  * count reaches zero.
00563  *
00564  * \param session The session to remove the datastore from
00565  * \param name The name of the datastore to remove
00566  */
00567 void ast_sip_session_remove_datastore(struct ast_sip_session *session, const char *name);
00568 
00569 /*!
00570  * \brief Send a reinvite or UPDATE on a session
00571  *
00572  * This method will inspect the session in order to construct an appropriate
00573  * session refresh request. As with any outgoing request in res_pjsip_session,
00574  * this will call into registered supplements in case they wish to add anything.
00575  *
00576  * Note: The on_request_creation callback may or may not be called in the same
00577  * thread where this function is called. Request creation may need to be delayed
00578  * due to the current INVITE transaction state.
00579  * 
00580  * \param session The session on which the reinvite will be sent
00581  * \param on_request_creation Callback called when request is created
00582  * \param on_sdp_creation Callback called when SDP is created
00583  * \param on_response Callback called when response for request is received
00584  * \param method The method that should be used when constructing the session refresh
00585  * \param generate_new_sdp Boolean to indicate if a new SDP should be created
00586  * \retval 0 Successfully sent refresh
00587  * \retval -1 Failure to send refresh
00588  */
00589 int ast_sip_session_refresh(struct ast_sip_session *session,
00590       ast_sip_session_request_creation_cb on_request_creation,
00591       ast_sip_session_sdp_creation_cb on_sdp_creation,
00592       ast_sip_session_response_cb on_response,
00593       enum ast_sip_session_refresh_method method,
00594       int generate_new_sdp);
00595 
00596 /*!
00597  * \brief Send a SIP response
00598  *
00599  * This will send the SIP response specified in tdata and
00600  * call into any registered supplements' outgoing_response callback.
00601  *
00602  * \param session The session on which to send the response.
00603  * \param tdata The response to send
00604  */
00605 void ast_sip_session_send_response(struct ast_sip_session *session, pjsip_tx_data *tdata);
00606 
00607 /*!
00608  * \brief Send a SIP request
00609  *
00610  * This will send the SIP request specified in tdata and
00611  * call into any registered supplements' outgoing_request callback.
00612  *
00613  * \param session The session to which to send the request
00614  * \param tdata The request to send
00615  */
00616 void ast_sip_session_send_request(struct ast_sip_session *session, pjsip_tx_data *tdata);
00617 
00618 /*!
00619  * \brief Creates an INVITE request.
00620  *
00621  * \param session Starting session for the INVITE
00622  * \param tdata The created request.
00623  */
00624 int ast_sip_session_create_invite(struct ast_sip_session *session, pjsip_tx_data **tdata);
00625 
00626 /*!
00627  * \brief Send a SIP request and get called back when a response is received
00628  *
00629  * This will send the request out exactly the same as ast_sip_send_request() does.
00630  * The difference is that when a response arrives, the specified callback will be
00631  * called into
00632  *
00633  * \param session The session on which to send the request
00634  * \param tdata The request to send
00635  * \param on_response Callback to be called when a response is received
00636  */
00637 void ast_sip_session_send_request_with_cb(struct ast_sip_session *session, pjsip_tx_data *tdata,
00638       ast_sip_session_response_cb on_response);
00639 
00640 /*!
00641  * \brief Retrieves a session from a dialog
00642  *
00643  * \param dlg The dialog to retrieve the session from
00644  *
00645  * \retval non-NULL if session exists
00646  * \retval NULL if no session
00647  *
00648  * \note The reference count of the session is increased when returned
00649  *
00650  * \note This function *must* be called with the dialog locked
00651  */
00652 struct ast_sip_session *ast_sip_dialog_get_session(pjsip_dialog *dlg);
00653 
00654 /*!
00655  * \brief Resumes processing of a deferred incoming re-invite
00656  *
00657  * \param session The session which has a pending incoming re-invite
00658  *
00659  * \note When resuming a re-invite it is given to the pjsip stack as if it
00660  *       had just been received from a transport, this means that the deferral
00661  *       callback will be called again.
00662  */
00663 void ast_sip_session_resume_reinvite(struct ast_sip_session *session);
00664 
00665 /*! \brief Determines whether the res_pjsip_session module is loaded */
00666 #define CHECK_PJSIP_SESSION_MODULE_LOADED()           \
00667    do {                       \
00668       CHECK_PJSIP_MODULE_LOADED();           \
00669       if (!ast_module_check("res_pjsip_session.so")) {   \
00670          return AST_MODULE_LOAD_DECLINE;        \
00671       }                    \
00672    } while(0)
00673 
00674 #endif /* _RES_PJSIP_SESSION_H */

Generated on Thu Apr 16 06:27:50 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6