Main Page | Modules | Class Hierarchy | Class List | Directories | File List | Class Members | File Members

zapISipUAStack Interface Reference
[ZAP SIP UA layer]

import "zapISipUAStack.idl";

List of all members.

Detailed Description

User Agent SIP stack interface.

Implemented by component '@mozilla.org/zap/sipstack;1'.

The User Agent SIP stack is the primary entry-point into the ZAP SIP module module. In conjunction with a user application component implementing zapISipRequestHandler, it constitutes the UAC and UAS components described in RFC3261.

For most of the time the User Agent stack handles all interfacing to the lower SIP protocol layers. It manages dialogs, provides stateful request servers/clients with automatic ACK/response retransmission logic and automatically handles certain error conditions (e.g. malformed requests, misdirected messages, concurrent invites).

The user application handles calls through zapISipRequestHandler callback interfaces. These can be set on either the zapISipUAStack or on individual zapISipDialogs. Some requests (e.g. OPTIONS) can sensibly be handled by the UA stack itself. See zapISipUAStack::requestHandler for more information about the routing of requests.

The user application initiates new calls through stateful 'request clients' obtained by calling zapISipUAStack::createNonInviteRequestClient(), zapISipUAStack::createInviteRequestClient(), zapISipUAStack::createSubscribeRequestClient(), zapISipDialog::createNonInviteRequestClient() and zapISipDialog::createInviteRequestClient().


Public Member Functions

void init (in zapISipRequestHandler handler, in nsIPropertyBag2 stackConfiguration)
 Initialize this SIP stack with the given request handler and configuration parameters.
void shutdown ()
 Shutdown the stack, releasing all network sockets.
zapISipNonInviteRC createNonInviteRequestClient (in zapISipAddress ToAddress, in zapISipAddress FromAddress, in ACString method,[array, size_is(count)] in zapISipAddress routeset, in unsigned long count, in unsigned long rcFlags)
 Obtain a generic request client object for transactionally sending a NON-INVITE request to ToAddress outside of a dialog.
zapISipNonInviteRC createRegisterRequestClient (in zapISipURI domain, in zapISipURI addressOfRecord, in zapISipAddress contactAddress,[array, size_is(count)] in zapISipAddress routeset, in unsigned long count, in unsigned long rcFlags)
 Obtain a request client object for transactionally sending a REGISTER request.
zapISipInviteRC createInviteRequestClient (in zapISipAddress ToAddress, in zapISipAddress FromAddress, in zapISipAddress contactAddress,[array, size_is(count)] in zapISipAddress routeset, in unsigned long count, in unsigned long rcFlags)
 Obtain a request client object for transactionally sending an INVITE request to ToAddress outside of a dialog.
zapISipSubscribeRC createSubscribeRequestClient (in zapISipAddress ToAddress, in zapISipAddress FromAddress, in zapISipAddress contactAddress, in ACString eventType,[array, size_is(count)] in zapISipAddress routeset, in unsigned long count, in unsigned long rcFlags)
 Obtain a request client object for transactionally sending a SUBSCRIBE request (RFC3265) to ToAddress outside of a dialog.
zapISipResponse formulateResponse (in ACString statusCode, in zapISipRequest request, in ACString toTag)
 Formulate a method-agnostic response with the given status code for the given request.
void appendAllowHeaders (in zapISipMessage message)
 Append Allow headers to the given message, using the method list passed in the configuration parameters to this stack (see init()).

Public Attributes

attribute zapISipRequestHandler requestHandler
 Remote requests received by the stack will be routed as follows:.
readonly attribute zapISipTransactionManager transactionManager
readonly attribute zapISipTransport transport
readonly attribute zapISipSyntaxFactory syntaxFactory
readonly attribute zapISipResolver resolver
readonly attribute zapISipAuthentication authentication
readonly attribute ACString hostName
readonly attribute ACString hostAddress
readonly attribute unsigned
short 		listeningPort
readonly attribute ACString instanceID
 The instance id of this UA as defined in draft-ietf-sip-gruu-05.txt.
readonly attribute AUTF8String userAgent
 The value that will be put into User-Agent headers of outgoing requests If this is equal to the empty string no User-Agent header will be added.
attribute boolean shortBranchParameters
 By default, zap uses UUIDs (RFC4122) in transaction branch parameters to guarantee uniqueness across space and time as required by RFC3261.
Request client flag constants for createNonInviteRequestClient(),
createInviteRequestClient() and createRegisterRequestClient()

const unsigned long ELIDE_DESTINATION_ROUTE_HEADER = 0x0001

Member Function Documentation

void zapISipUAStack::appendAllowHeaders (  in zapISipMessage  message  ) 
 

Append Allow headers to the given message, using the method list passed in the configuration parameters to this stack (see init()).

zapISipInviteRC zapISipUAStack::createInviteRequestClient (  in zapISipAddress  ToAddress,
in zapISipAddress  FromAddress,
in zapISipAddress  contactAddress,
[array, size_is(count)] in zapISipAddress  routeset,
in unsigned long  count,
in unsigned long  rcFlags
) 
 

Obtain a request client object for transactionally sending an INVITE request to ToAddress outside of a dialog.

The zapISipInviteRC::request attribute will be initialized as for createNonInviteRequestClient(), and, in addition, a Contact header set to the given Contact address will be added.

zapISipNonInviteRC zapISipUAStack::createNonInviteRequestClient (  in zapISipAddress  ToAddress,
in zapISipAddress  FromAddress,
in ACString  method,
[array, size_is(count)] in zapISipAddress  routeset,
in unsigned long  count,
in unsigned long  rcFlags
) 
 

Obtain a generic request client object for transactionally sending a NON-INVITE request to ToAddress outside of a dialog.

The zapISipNonInviteRC::request attribute will be initialized as follows (RFC3261 8.1.1):

  • method: will be set to the given method.
  • requestURI and route set: will be set from the ToAddress uri part and the given route following the procedures outlined in RFC3261 8.1.1 and 12.2.1.1.
  • Via header: a new Via header will be created. sent-protocol and sent-by will be filled in when the request is sent by the transport.
  • To header: will be set to the given ToAddress.
  • From header: will be set to the given FromAddress. A new 'tag' will be generated.
  • Call-ID header: will be set to a new call id.
  • CSeq: will be set to a number < 2^31
  • Max-Forwards header: will be set to 70
  • User-Agent: will be set to the value of the userAgent attribute if it is != ""
  • If method != 'ACK', Supported headers will be added for all option tags specified in the 'extensions' parameter passed to init().

zapISipNonInviteRC zapISipUAStack::createRegisterRequestClient (  in zapISipURI  domain,
in zapISipURI  addressOfRecord,
in zapISipAddress  contactAddress,
[array, size_is(count)] in zapISipAddress  routeset,
in unsigned long  count,
in unsigned long  rcFlags
) 
 

Obtain a request client object for transactionally sending a REGISTER request.

The zapISipNonInviteRC::request attribute will be initialized as for createNonInviteRequestClient(), with the following exceptions:

  • The requestURI and route set will be based on the given domain parameter (rather than the ToAddress as in createNonInviteRequestClient()).
  • The ToAddress will be set to the given addressOfRecord.
  • The FromAddress will be set to the given addressOfRecord.
  • A Contact header will be added, set to the given Contact address

zapISipSubscribeRC zapISipUAStack::createSubscribeRequestClient (  in zapISipAddress  ToAddress,
in zapISipAddress  FromAddress,
in zapISipAddress  contactAddress,
in ACString  eventType,
[array, size_is(count)] in zapISipAddress  routeset,
in unsigned long  count,
in unsigned long  rcFlags
) 
 

Obtain a request client object for transactionally sending a SUBSCRIBE request (RFC3265) to ToAddress outside of a dialog.

The zapISipSubscribeRC::request attribute will be initialized as for createInviteRequestClient(), and, in addition, an Event header set to the given eventType will be added.

zapISipResponse zapISipUAStack::formulateResponse (  in ACString  statusCode,
in zapISipRequest  request,
in ACString  toTag
) 
 

Formulate a method-agnostic response with the given status code for the given request.

For transactional requests, clients should generally not call this method, but instead call formulateResponse() on the request server (zapISipNonInviteRS or zapISipInviteRS), as this will formulate the response in a way appropriate to the given request.

Responses are constructed as follows (following RFC3261):

  • statusCode : set to the given status code (SC)
  • reasonPhrase: set to the standard RFC3261 english phrase appropriate for the status code
  • From : copied from request
  • Call-ID : copied from request
  • CSeq : copied from request
  • Via : all copied from request
  • To : copied from request

If the request does not contain a To tag, SC!=100 and 'toTag'==null, a new tag will be created and set on the To header.

If 'toTag'!=null it will be set on the To header. The request must not already contain a tag or an error will be thrown.

For SC==405: Allow headers will be added with appendAllowHeaders()

For SC==2XX: Supported headers will be added for all option tags specified in the 'extensions' parameter passed to init().

void zapISipUAStack::init (  in zapISipRequestHandler  handler,
in nsIPropertyBag2  stackConfiguration
) 
 

Initialize this SIP stack with the given request handler and configuration parameters.

Valid configuration parameters:

  • ACString "instance_id": instance id of the UA as defined in draft-ietf-sip-gruu-05.txt. This must be a UUID URN string (RFC4122). Default: A new UUID URN will be generated if this parameter is not given.
  • unsigned short "port_base" : port at which to listen for tcp and udp SIP traffic. If the port is not available, the next available port greater than port_base will be used instead. Default: 5060
  • ACString "methods" : comma-separated list of SIP methods understood by the UA. Will be used to construct Allow headers and influences error responses returned for requests handled by the UAStack. Default: "OPTIONS"
  • ACString "extensions" : comma-separated list of extensions (option tags) understood by the UA. Will be used to filter incoming requests with Require headers and to construct Supported headers. Default: ""
  • boolean "rport_client" : if 'true', requests formulated by the stack will include an 'rport' parameter in the top via, and INVITE requests will be retransmitted every 20s as specified in RFC3581 3. Default: true
  • boolean "short_branch_parameters" : if 'true', zap will use 32 bit branch parameters instead of UUIDs. See zapISipUAStack::shortBranchParameters. Default: false
  • AUTF8String "user_agent" : value for the User-Agent header of outgoing requests. If this is equal to the empty string, no User-Agent headers will be added to requests. Default: ""

void zapISipUAStack::shutdown (   ) 
 

Shutdown the stack, releasing all network sockets.

It is the user application's responsibility to terminate any dialogs or ongoing transactions before shutting down the stack.

Member Data Documentation

readonly attribute zapISipAuthentication zapISipUAStack::authentication
 

const unsigned long zapISipUAStack::ELIDE_DESTINATION_ROUTE_HEADER = 0x0001
 

readonly attribute ACString zapISipUAStack::hostAddress
 

readonly attribute ACString zapISipUAStack::hostName
 

readonly attribute ACString zapISipUAStack::instanceID
 

The instance id of this UA as defined in draft-ietf-sip-gruu-05.txt.

This will be set to the value of the 'instance_id' parameter handed to the UAStack in init().

readonly attribute unsigned short zapISipUAStack::listeningPort
 

attribute zapISipRequestHandler zapISipUAStack::requestHandler
 

Remote requests received by the stack will be routed as follows:.

  • Requests with Require headers will be checked against the list of extensions in the configuration parameters. If there are unsupported extensions, a 420 (Bad Extension) will be generated.

  • Requests with a To tag that don't match any ongoing dialog will be answered with 481 (Call/Transaction Does Not Exist).

  • If the request is an ACK it will be routed to the pending INVITE or silently dropped if there is no pending INVITE waiting for ACK.

  • If the request is an in-dialog INVITE request and there is a pending INVITE on the dialog, a 500 or 491 will be generated following RFC3261 14.2.

  • If the request is an in-dialog request and the dialog has a request handler set, it will get a chance to handle the request.

  • If the dialog request handler doesn't handle the request, or if the request is outside of a dialog it will be passed to the user application component's request handler set on the UAStack.

  • If the request still isn't handled it will be handled by the UAStack itself. The UAStack only handles ACK, BYE, CANCEL, and OPTIONS , and only if they appear in the "methods" configuration parameter. For other requests a 405 (Method Not Allowed) or 500 (Server Internal Error) will be returned, depending on whether or not the request method is listed in the "methods" configuration parameter.

For in-dialog requests matching an active dialog, the default BYE handler will generate 200 (OK) and terminate the dialog. For BYE requests without a To tag, a 481 response will be generated. (RFC3261 15.1.2).

The default OPTIONS handler returns 200 (OK) with Allowed headers constructed by appendAllowHeaders().

The default CANCEL handler returns 481 (Transaction Does Not Exist) if there is no matching transaction, or 200 (OK) otherwise. In addition, if a matching INVITE server transaction is found for which no final response has been sent yet, and this transaction is owned by a zapISipInviteRS, the transaction will be cancelled by sending a 487 (Request Terminated), and the associated zapISipInviteRSListener will be informed of the cancellation with a call to zapISipInviteRSListener::notifyCancelled().

readonly attribute zapISipResolver zapISipUAStack::resolver
 

attribute boolean zapISipUAStack::shortBranchParameters
 

By default, zap uses UUIDs (RFC4122) in transaction branch parameters to guarantee uniqueness across space and time as required by RFC3261.

The resulting branch parameters are 39 characters long, which some endpoints have trouble processing. If this is set to 'true', zap will use 32bit branch parameters instead.

Can also be set from init() in the 'short_branch_parameters' parameter.

readonly attribute zapISipSyntaxFactory zapISipUAStack::syntaxFactory
 

readonly attribute zapISipTransactionManager zapISipUAStack::transactionManager
 

readonly attribute zapISipTransport zapISipUAStack::transport
 

readonly attribute AUTF8String zapISipUAStack::userAgent
 

The value that will be put into User-Agent headers of outgoing requests If this is equal to the empty string no User-Agent header will be added.

Will be set to the value of the 'user_agent' parameter handed to the UAStack in init().

The documentation for this interface was generated from the following file:
Generated on Fri Nov 21 12:00:06 2008 for Mozilla ZAP by  doxygen 1.4.4