Difference between revisions of "How to use dum"

From reSIProcate
Jump to navigation Jump to search
 
(13 intermediate revisions by 3 users not shown)
Line 1: Line 1:
== Overview ==
+
=== Introduction to the DialogUsageManager ===
 +
The DialogUsageManager (or DUM) class sits on top of the transaction layer of the SIP stack. It keeps track of all of the Dialog-related data structures in multiple DialogSets. Each DialogSet contains all the Dialogs created by an initial request, which share the same SIP Call-Id and From tag. Inside a specific DialogSet on the UAC side, a BaseCreator can represent the intial request that generated the dialog. The DialogSet also contains several objects derived from BaseUsage that are using this particular dialog. There are several Usages available to a dialog: one InviteSession, one Registration, one Publication, multiple Subscriptions and multiple OutOfDialogRequests. Note: OutOfDialogRequests resemble a dialog, but are actually transactions that do not fit of the other categories. Requests that result in OutOfDialogRequests are MESSAGE and OPTIONS.
  
The DialogUsageManager (or dum) is the main interface to the dum library used by the application. Any dum application needs to create a dum object. In typical applications there would be a single dum object for the entire application. This single dum object could manage multiple user agents. By default the construction of the dum object creates a SipStack. dum has the following roles and responsibilities:
+
An initial SIP request is created by calling the makeX interfaces on the DUM. It is then sent using the send interface on the DUM. When a response is returned for the request, a callback from one of the Handler classes notifies the application. This will pass up some type of client or server usages class that can be used to send aditional messages and responses in the context of this particularr usage of the dialog.
* Manages profiles
 
* Manages AppDialogSetFactory
 
* Manages and stores Handlers (DialogSetHandler, InviteSessionHandler, ClientRegistrationHandler, ServerRegistrationHandler, ClientSubscriptionHandler, ServerSubscriptionHandler, ClientPublicationHandler, ServerPublicationHandler, OutOfDialogHandler, ClientPagerMessageHandler, ServerPagerMessageHandler, RegistrationPersistenceManager)
 
* Manages redirections (RedirectManager)
 
* Manages client authentication (ClientAuthManager)
 
* Manages server authentication (ServerAuthManager)
 
* Manages SipStack and optional StackThread
 
* Interface to add new Transports
 
* Manages handles to Usages (HandleManager)
 
* Provides interfaces to create new sessions as a UAC (invite, subscription, publication, registration, pager, others)
 
* Provides interfaces to find particular usages based on a DialogId
 
  
== Usages ==
+
=== [[DUM Definitions|Definitions]] ===
[[Image:DUM_Usage_Inheritance.png]]
 
* Usages are blah, blah, blah.
 
* Describe what handles are here.
 
* [[ClientRegistration]]
 
* [[ServerRegistration]]
 
* [[ClientPublication]]
 
* [[ServerPublication]]
 
* [[ClientSubscription]]
 
* [[ServerSubscription]]
 
* [[Invitation]]
 
* [[Pager]]
 
* [[OutOfDialogReq]]
 
  
== Profiles ==
+
=== How to use DUM ===
* [[Dealing with Mulitple User Profiles]]
+
*[[DUM Handlers|Handlers]]
 
+
*[[DUM Application Initialization|Application Initialization]]
== Details ==
+
*[[DUM Application Shutdown|Application Shutdown]]
* [[Threading]]  
+
*[[DUM Registering and Authenticating]]
* [[Server Usages]]
+
*[[DUM Creating New Sessions and Requests|Creating New Sessions and Requests]]
* [[Managing Transports]]
+
*[[DUM Ending an Invite Session|Ending an Invite Session]]
* [[Finding Usages]]
+
*[[DUM Creating New Client Subscriptions|Creating New Client Subscriptions]]
* [[Handling Invite Sessions]]
+
*[[DUM Associating Application Data with DialogSets and Dialogs|Associating Application Data with DialogSets and Dialogs]]
* [[Handling Registrations]]
+
*[[DUM Configuration and Profiles|Configuration and Profiles]]
* [[Handling Subscriptions]]
+
*[[DUM Procedures|Procedures]]
* [[Handling Publications]]
+
*[[DUM Advanced Procedures|Advanced DUM Procedures]]
* [[Handling Pager Messaging]]
+
*[[DUM Overridable Managers|Overridable Managers]]
* [[Dealing with Refer]]
+
*[[DUM Exception Handling|Exception Handling]]
* [[Dealing with Redirection]]
+
*[[DUM Threading|Threading]]
* [[Dealing with Digest Authentication]]
+
*[[DUM Application Timers]]
* [[Dealing with Complex Offer/Answer]]
+
*[[DUM Common Errors|Common Errors]]
* [[Associating Application Data with Dialogs/DialogSets]]
+
*[[DUM Client Outbound Support|Client Outbound Support (RFC 5626)]]
 
 
 
 
The DialogUsageManager(or DUM) is the class that keeps track of all of the Dialog related data structures and sits on top of the transaction layer of the SIP stack. It keeps track of multiple DialogSets which contain Dialogs.  Each DialogSet contains all the Dialogs that were created by a common initial request. They all share the same SIP Call-Id and from tag from the orginal request. Inside a specific DialogSet there can be some type of BaseCreator that represents the intial request that generated the dialog.  This will only exist on the UAC side.  The DialogSet also contains several objects derived from BaseUsage that are using this particular dialog. There are several types of things that are a Usage of a dialog. There can be one InviteSession, one Registration, one Publication, multiple Subscriptions and multiple OutOfDialogRequests. Note the name OutOfDialog is a little weird - OutOfDialog requests are actually in a thing a lot like a dialog but are transactions that are not in one of the other categories. Typically messages that result in OutOfDialogRequests are MESSAGE and OPTIONS.
 
 
 
An initial SIP Request is created by calling the makeX interfaces on the DUM. It is then sent using the send interface on the DUM.  When a response is returned for the request, a callback from one of the Handler classes will be called to notify the application about the incoming events.  This
 
will pass up some type of client or server usages class that can be used to send aditional messages and responses in the context of this particularr usage of the Dialog.
 
 
 
== Definitions ==
 
 
 
; DialogUsageManager : Main class that keeps track of all the DialogSet, Dialog, and Usage objects.
 
; User Agent Server (UAS) : A user agent server is a logical entity that generates a response to a SIP request.  The response accepts, rejects, or redirects the request.  This role lasts only for the duration of that transaction.  In other words, if a piece of software responds to a request, it acts as a UAS for the duration of that transaction.  If it generates a request later, it assumes the role of a user agent client for the processing of that transaction. (Definition from http://www.faqs.org/rfcs/rfc3261.html)
 
; User Agent Client (UAC) : A user agent client is a logical entity that creates a new request, and then uses the client transaction state machinery to send it.  The role of UAC lasts only for the duration of that transaction.  In other words, if a piece of software initiates a request, it acts as a UAC for the duration of that transaction.  If it receives a request later, it assumes the role of a user agent server for the processing of that transaction.  (Definition from http://www.faqs.org/rfcs/rfc3261.html)
 
; DialogSet : A container class that will hold a set of dialogs that were generated from a common request. They share the same call-id and the same from tag in the request that generated the dialog.
 
; Monolog : A term to generically describe the container for the usage created from a non-dialog creating request such as REGISTER or PUBLISH. Monologs exist for both the UAC and UAS. (This might better be named MonoUsage).
 
; Dialog : A container holding such things and local and remote CSEQ, URI, Call-ID and such as defined by the SIP standard.
 
; DialogID : An identifier that uniquely finds a a Dialog by Call-ID, and To and From tags.
 
; DialogSetID : An identifier that uniquily identifies a Dialog-Set and is formed from Call-ID and From tag.
 
; Usages : These are the objects are are using a dialog. They include ClientInviteSession, ClientOutOfDialogReq, ClientPublication, ClientRegistration, ClientSubscription, ServerInviteSession, ServerOutOfDialogReq, ServerPublication, ServerRegistration, and ServerSubscription. Notice that this is almost, but not entirely, what "usage" means in the IETF specifications. An Invite session or a Subscription is a usage there. The old "psuedo-dialog" concept surrounding registration should be called a Psuedo-Usage or at best Mono-Usage. At the moment, however, these are all reflected in code as "Usages"
 
; Handlers : These are objects uses to derive class from that allow callbacks from this layer to the application. They include InviteSessionHandler, OutOfDialogHandler, RegistrationHandler, SubscriptionHandler, and PublictionHandler.
 
; Handles : All the Usages and Handlers are not really exposed to the applications using this layer.  Instead, handles to them are passed out.  When the applications goes to use a handle, the underlying object may have been deleted and the applications must be prepared for this not to work.
 

Latest revision as of 10:15, 27 February 2011

Introduction to the DialogUsageManager[edit]

The DialogUsageManager (or DUM) class sits on top of the transaction layer of the SIP stack. It keeps track of all of the Dialog-related data structures in multiple DialogSets. Each DialogSet contains all the Dialogs created by an initial request, which share the same SIP Call-Id and From tag. Inside a specific DialogSet on the UAC side, a BaseCreator can represent the intial request that generated the dialog. The DialogSet also contains several objects derived from BaseUsage that are using this particular dialog. There are several Usages available to a dialog: one InviteSession, one Registration, one Publication, multiple Subscriptions and multiple OutOfDialogRequests. Note: OutOfDialogRequests resemble a dialog, but are actually transactions that do not fit of the other categories. Requests that result in OutOfDialogRequests are MESSAGE and OPTIONS.

An initial SIP request is created by calling the makeX interfaces on the DUM. It is then sent using the send interface on the DUM. When a response is returned for the request, a callback from one of the Handler classes notifies the application. This will pass up some type of client or server usages class that can be used to send aditional messages and responses in the context of this particularr usage of the dialog.

Definitions[edit]

How to use DUM[edit]