The OpenNET Project / Index page

[ новости /+++ | форум | теги | ]

Интерактивная система просмотра системных руководств (man-ов)

 ТемаНаборКатегория 
 
 [Cписок руководств | Печать]

sip_stack_init (3)
  • >> sip_stack_init (3) ( Solaris man: Библиотечные вызовы )
  •  

    NAME

    sip_stack_init - initializes SIP stack
     
    

    SYNOPSIS

    cc [ flag ... ] file ... -lsip [ library ... ]
    #include <sip.h>
    
    int sip_stack_init(sip_stack_init_t * stack_val);
    

     

    DESCRIPTION

    The sip_stack_init() function is used to initialize the SIP stack. The stack can be initialized by a process only once. Any shared library that is linked with a main program or another library that has already initialized the stack will encounter a failure when trying to initialize the stack.

    The initialization structure is given by:

    typedef struct sip_stack_init_s {
       int                      sip_version;
       uint32_t                 sip_stack_flags;
       sip_io_pointers_t       *sip_io_pointers;
       sip_ulp_pointers_t      *sip_ulp_pointers;
       sip_header_function_t   *sip_function_table;
    };
    

    sip_version

    This must be set to SIP_STACK_VERSION.

    sip_stack_flags

    If the application wants the SIP stack to maintain dialogs, this flag must be set to SIP_STACK_DIALOGS. Otherwise, it must be set to 0. If SIP_STACK_DIALOGS is not set, the stack does not deal with dialogs at all.

     

    Upper Layer Registrations

    These include callbacks that are invoked to deliver incoming messages or error notification.

    The callback functions should not create a thread and invoke a function that could recursively invoke the callback. For example, the callback function for a transition state change notification should not create a thread to send a SIP message that results in a change in the state of the transaction, which would again invoke the callback function.

    The registration structure is supplied by:

    typedef struct sip_ulp_pointers_s {
        void      (*sip_ulp_recv)(const sip_conn_object_t,
                        sip_msg_t, const sip_dialog_t);
        uint_t    (*sip_ulp_timeout)(void *, 
                        void (*func)(void *),
                        struct timeval *);
        boolean_t (*sip_ulp_untimeout)(uint_t);
        int       (*sip_ulp_trans_error)
                        (sip_transaction_t, int, void *);
        void      (*sip_ulp_dlg_del)(sip_dialog_t,
                        sip_msg_t, void *);
        void      (*sip_ulp_trans_state_cb)
                  (sip_transaction_t, sip_msg_t,
                        int, int);
        void      (*sip_ulp_dlg_state_cb)(sip_dialog_t,
                        sip_msg_t, int, int);
    }sip_io_pointers_t;
    

    sip_ulp_recv

    This is a mandatory routine that the application registers for the stack to deliver an inbound SIP message. The SIP stack invokes the function with the connection object on which the message arrived, the SIP message, and any associated dialog.

    The SIP message is freed once the function returns. If the application wishes to use the message beyond that, it has to hold a reference on the message using sip_hold_msg(). Similarly, if the application wishes to cache the dialog, it must hold a reference on the dialog using sip_hold_msg().

    sip_ulp_timeout
    sip_ulp_untimeout

    An application can register these two routines to implement its own routines for the stack timers. Typically, an application should allow the stack to use its own built-in timer routines. The built-in timer routines are used only by the stack and are not available to applications. If the application registers one routine, it must also register the other.

    These functions must be registered for single-threaded application. Otherwise, the timer thread provided by the stack could result in invoking a registered callback function.

    sip_ulp_trans_error

    The application can register this routine to be notified of a transaction error. An error can occur when the transaction layer tries to send a message using a cached connection object which results in a failure. If this routine is not registered the transaction is terminated on such a failure. The final argument is for future use. It is always set to NULL.

    sip_ulp_dlg_del

    An application can register this routine to be notified when a dialog is deleted. The dialog to be deleted is passed along with the SIP message which caused the dialog to be deleted. The final argument is for future use. It is always set to NULL.

    sip_ulp_trans_state_cb
    sip_ulp_dlg_state_cb

    If these callback routines are registered, the stack invokes sip_ulp_trans_state_cb when a transaction changes states and sip_ulp_dlg_state_cb when a dialog changes states.

     

    Connection Manager Interface

    The connection manager interfaces must be registered by the application to provide I/O related functionality to the stack. These interfaces act on a connection object that is defined by the application. The application registers the interfaces for the stack to work with the connection object. The connection object is application defined, but the stack requires that the first member of the connection object is a void *, used by the stack to store connection object specific information which is private to the stack.

    The connection manager structure is supplied by:

    typedef struct sip_io_pointers_s {
           int     (*sip_conn_send)(const sip_conn_object_t, char *, int);
           void    (*sip_hold_conn_object)(sip_conn_object_t);
           void    (*sip_rel_conn_object)(sip_conn_object_t);
           boolean_t       (*sip_conn_is_stream)(sip_conn_object_t);
           boolean_t       (*sip_conn_is_reliable)(sip_conn_object_t);
           int     (*sip_conn_remote_address)(sip_conn_object_t, struct sockaddr *,
                       socklen_t *);
           int     (*sip_conn_local_address)(sip_conn_object_t, struct sockaddr *,
                       socklen_t *);
           int     (*sip_conn_transport)(sip_conn_object_t);
           int     (*sip_conn_timer1)(sip_conn_object_t);
           int     (*sip_conn_timer2)(sip_conn_object_t);
           int     (*sip_conn_timer4)(sip_conn_object_t);
           int     (*sip_conn_timerd)(sip_conn_object_t);
    }sip_io_pointers_t;
    

    sip_conn_send

    This function is invoked by the stack after processing an outbound SIP message. This function is responsible for sending the SIP message to the peer. A return of 0 indicates success. The SIP message is passed to the function as a string, along with the length information and the associated connection object.

    sip_hold_conn_object
    sip_rel_conn_object

    The application provides a mechanism for the stack to indicate that a connection object is in use by the stack and must not be freed. The stack uses sip_hold_conn_object to indicate that the connection object is in use and sip_rel_conn_object to indicate that it has been released. The connection object is passed as the argument to these functions. The stack expects that the application will not free the connection object if it is in use by the stack.

    sip_conn_is_stream

    The stack uses this to determine whether the connection object, passed as the argument, is byte-stream oriented. Byte-stream protocols include TCP while message-based protocols include SCTP and UDP.

    sip_conn_is_reliable

    The stack uses this to determine whether the connection object, passed as the argument, is reliable. Reliable protocols include TCP and SCTP. Unreliable protocols include UDP.

    sip_conn_local_address
    sip_conn_remote_address

    These two interfaces are used by the stack to obtain endpoint information for a connection object. The sip_conn_local_address provides the local address/port information. The sip_conn_remote_address provides the address/port information of the peer. The caller allocates the buffer and passes its associated length along with it. On return, the length is updated to reflect the actual length.

    sip_conn_transport

    The stack uses this to determine the transport used by the connection object, passed as the argument. The transport could be TCP, UDP, SCTP.

    sip_conn_timer1
    sip_conn_timer2
    sip_conn_timer4
    sip_conn_timerd

    These four interfaces may be registered by an application to provide connection object specific timer information. If these are not registered the stack uses default values.

    The interfaces provide the timer values for Timer 1 (RTT estimate - default 500 msec), Timer 2 (maximum retransmit interval for non-INVITE request and INVITE response - default 4 secs), Timer 4 (maximum duration a message will remain in the network - default 5 secs) and Timer D (wait time for response retransmit interval - default 32 secs).

     

    Custom SIP headers

    In addition to the SIP headers supported by the stack, an application can optionally provide a table of custom headers and associated parsing functions. The table is an array with an entry for each header. If the table includes headers supported by the stack, parsing functions or other application-specific table entries take precedence over libsip supported headers. The header table structure is supplied by:

    typedef struct header_function_table {
        char      *header_name;
        char      *header_short_name;
        int       (*header_parse_func)
                  (struct sip_header *,
                        struct sip_parsed_header **);
        boolean_t (*header_check_compliance)
                  (struct sip_parsed_header *);
        boolean_t (*header_is_equal)
                  (struct sip_parsed_header *,
                        struct sip_parsed_header *);
        void      (*header_free)
                  (struct sip_parsed_header *);
    }
    

    header_name

    The full name of the header. The application must ensure that he name does not conflict with existing headers. If it does, the one registered by the application takes precedence.

    header_short_name

    Compact name, if any, for the header.

    header_parse_func

    The parsing function for the header. The parser will set the second argument to the resulting parsed structure. A return value of 0 indicates success.

    header_free

    The function that frees the parsed header

    header_check_compliance

    An application can optionally provide this function that will check if the header is compliant or not. The compliance for a custom header will be defined by the application.

    header_is_equal

    An application can optionally provide this function to determine whether two input headers are equivalent. The equivalence criteria is defined by the application.

     

    RETURN VALUES

    On success sip_stack_init() returns 0. Otherwise, the function returns the error value.

    The value of errno is not changed by these calls in the event of an error.  

    ERRORS

    On failure, the sip_stack_init() function returns the following error value:

    EINVAL

    If the stack version is incorrect, or if any of the mandatory functions is missing.

     

    ATTRIBUTES

    See attributes(5) for descriptions of the following attributes:

    ATTRIBUTE TYPEATTRIBUTE VALUE

    Interface StabilityCommitted

    MT-Level

     

    SEE ALSO

    libsip(3LIB)


     

    Index

    NAME
    SYNOPSIS
    DESCRIPTION
    Upper Layer Registrations
    Connection Manager Interface
    Custom SIP headers
    RETURN VALUES
    ERRORS
    ATTRIBUTES
    SEE ALSO


    Поиск по тексту MAN-ов: 




    Партнёры:
    PostgresPro
    Inferno Solutions
    Hosting by Hoster.ru
    Хостинг:

    Закладки на сайте
    Проследить за страницей
    Created 1996-2024 by Maxim Chirkov
    Добавить, Поддержать, Вебмастеру