README
¶
SIP Stack
Documentation
¶
Index ¶
Constants ¶
View Source
const PORT_5060 = 5060
*
- Port Constant: Default port 5060. This constant should only be used
- when the transport of the ListeningPoint is set to UDP, TCP or SCTP. * *
View Source
const PORT_5061 = 5061
*
- Port Constant: Default port 5061. This constant should only be used
- when the transport of the Listening Point is set to TLS over TCP or TCP
- assuming the scheme is "sips". * *
View Source
const SCTP = "SCTP"
*
- Transport constant: SCTP * *
View Source
const TCP = "TCP"
*
- Transport constant: TCP
View Source
const TLS = "TLS"
*
- Transport constant: TLS over TCP * *
View Source
const UDP = "UDP"
*
- Transport constant: UDP
Variables ¶
View Source
var DIALOGSTATE_COMPLETED = m_dialogStateArray[_DIALOGSTATE_COMPLETED]
*
- This constant value indicates that the dialog state is "Completed".
View Source
var DIALOGSTATE_CONFIRMED = m_dialogStateArray[_DIALOGSTATE_CONFIRMED]
*
- This constant value indicates that the dialog state is "Confirmed".
View Source
var DIALOGSTATE_EARLY = m_dialogStateArray[_DIALOGSTATE_EARLY]
*
- This constant value indicates that the dialog state is "Early".
View Source
var DIALOGSTATE_TERMINATED = m_dialogStateArray[_DIALOGSTATE_TERMINATED]
*
- This constant value indicates that the dialog state is "Terminated".
View Source
var TIMEOUT_RETRANSMIT = m_timeoutArray[_TIMEOUT_RETRANSMIT]
*
- This constant value indicates the "Retransmit" timeout.
View Source
var TIMEOUT_TRANSACTION = m_timeoutArray[_TIMEOUT_TRANSACTION]
*
- This constant value indicates the "Transaction" timeout.
View Source
var TRANSACTIONSTATE_CALLING = m_transStateArray[_TRANSACTIONSTATE_CALLING]
*
- This constant value indicates that the transaction state is "Calling".
View Source
var TRANSACTIONSTATE_COMPLETED = m_transStateArray[_TRANSACTIONSTATE_COMPLETED]
*
- This constant value indicates that the transaction state is "Completed".
View Source
var TRANSACTIONSTATE_CONFIRMED = m_transStateArray[_TRANSACTIONSTATE_CONFIRMED]
*
- This constant value indicates that the transaction state is "Confirmed".
View Source
var TRANSACTIONSTATE_PROCEEDING = m_transStateArray[_TRANSACTIONSTATE_PROCEEDING]
*
- This constant value indicates that the transaction state is "Proceeding".
View Source
var TRANSACTIONSTATE_TERMINATED = m_transStateArray[_TRANSACTIONSTATE_TERMINATED]
*
- This constant value indicates that the transaction state is "Terminated".
View Source
var TRANSACTIONSTATE_TRYING = m_transStateArray[_TRANSACTIONSTATE_TRYING]
*
- This constant value indicates that the transaction state is "Trying".
Functions ¶
This section is empty.
Types ¶
type ClientTransaction ¶
type ClientTransaction interface {
Transaction
/**
* Sends the Request which created this ClientTransaction. When an
* application wishes to send a Request message, it creates a Request from
* the {@link javax.sip.message.MessageFactory} and then creates a new
* ClientTransaction from
* {@link SipProvider#getNewClientTransaction(Request)}. Calling this method
* on the ClientTransaction sends the Request onto the network. The Request
* message gets sent via the ListeningPoint information of the SipProvider
* that is associated to this ClientTransaction.
* <p>
* This method assumes that the Request is sent out of Dialog. It uses
* the Router to determine the next hop. If the Router returns a empty
* iterator, and a Dialog is associated with the outgoing request of the
* Transaction then the Dialog route set is used to send the outgoing
* request.
* <p>
* This method implies that the application is functioning as either a UAC
* or a stateful proxy, hence the underlying implementation acts statefully.
*
* @throws SipException if the SipProvider cannot send the Request for any
* reason.
* @see Request
*/
SendRequest() (SipException error)
/**
* Creates a new Cancel message from the Request associated with this client
* transaction. The CANCEL request, is used to cancel the previous request
* sent by this client transaction. Specifically, it asks the UAS to cease
* processing the request and to generate an error response to that request.
* A CANCEL request constitutes its own transaction, but also references
* the transaction to be cancelled. CANCEL has no effect on a request to
* which a UAS has already given a final response.
* <p>
* Note that both the transaction corresponding to the original request and
* the CANCEL transaction will complete independently. However, a UAC
* canceling a request cannot rely on receiving a 487 (Request Terminated)
* response for the original request, as an RFC 2543 compliant UAS will
* not generate such a response. Therefore if there is no final response for
* the original request the application will receieve a TimeoutEvent with
* {@link javax.sip.Timeout#TRANSACTION} and the client should then consider the
* original transaction cancelled.
* <ul>
* <li> UAC - A UAC should not send a CANCEL request to any request explicitly
* supported by this specification other than INVITE request. The reason
* being requests other than INVITE are responded to immediately and sending
* a CANCEL for a non-INVITE request would always create a race condition.
* CANCELs are useful as a UAC can not send a BYE request on a dialog
* until receipt of 2xx final response to the INVITE request. The CANCEL
* attempts to force a non-2xx response to the INVITE, therefore if a UAC
* wishes to give up on its call attempt entirely it can send a CANCEL.
* <li>Stateful proxies - A stateful proxy may generate CANCEL requests
* for:
* <ul>
* <li>INVITE Requests - A CANCEL can be sent on pending INVITE client
* transactions based on the period specified in the INVITE's Expires
* header field elapsing. However, this is generally unnecessary since
* the endpoints involved will take care of signaling the end of the
* transaction.
* <li> Other Requests - A CANCEL can be sent on any other request the proxy
* has generated at any time, subject to receiving a provisional response
* to that request.
* </ul>
* </ul>
*
* @return the new cancel Request specific to the Request of this client
* transaction.
* @throws SipException if this method is called to cancel a request that
* can't be cancelled i.e. ACK.
*/
CreateCancel() (r message.Request, SipException error)
/**
* Creates a new Ack message from the Request associated with this client
* transaction. This ACK can be used to acknowledge the response to the
* request sent by this transaction. It is recommended that a
* ClientTransaction be created to send the ACK.
*
* @return the new ACK Request specific to the Request of this client
* transaction.
* @throws SipException if this method is called before a final response
* is received for the transaction.
*/
CreateAck() (r message.Request, SipException error)
}
*
- A client transaction is used by a User Agent Client application to send
- Request messages to a User Agent Server application.
- The client transaction is also used to match Responses from the User Agent
- Server to fire Response events to the SipListener for a specific client
- transaction. This interfaces enables an application to send a
- {@link javax.sip.message.Request}'s statefully. A new client transaction
- is generated by the application calling the
- {@link SipProvider#getNewClientTransaction(Request)} method.
- <p>
- A client transaction of the transaction layer is represented by a finite
- state machine that is constructed to process a particular request under
- the covers of a stateful SipProvider. The transaction layer handles
- application-layer retransmissions, matching of responses to requests, and
- application-layer timeouts. Any task that a User Agent Client
- accomplishes takes place using a series of transactions.
- <p>
- The client transaction must be unique within the underlying
- implementation. A common way to create this value is to compute a
- cryptographic hash of the To tag, From tag, Call-ID header field, the
- Request-URI of the request received (before translation), the topmost Via
- header, and the sequence number from the CSeq header field, in addition to
- any Proxy-Require and Proxy-Authorization header fields that may be present.
- The algorithm used to compute the hash is implementation-dependent.
- <p>
- For the detailed client transaction state machines refer to Chapter
- 17 of <a href="http://www.ietf.org/rfc/rfc3261.txt">RFC 3261</a>, the
- allowable transitions are summarized below:
- <p>
- <b>Invite Transaction:</b><br>
- Calling --> Proceeding --> Completed --> Terminated
- <p>
- <b>Non-Invite Transaction:</b><br>
- Trying --> Proceeding --> Completed --> Terminated *
- @author Rain Liu
type Dialog ¶
type Dialog interface {
/**
* Returns the Address identifying the local party. This is the value of
* the From header of locally initiated requests in this dialog when
* acting as an User Agent Client.
* <p>
* This is the value of the To header of recieved responses in this
* dialog when acting as an User Agent Server.
*
* @return the address object of the local party.
*/
GetLocalParty() address.Address
/**
* Returns the Address identifying the remote party. This is the value of
* the To header of locally initiated requests in this dialog when
* acting as an User Agent Client.
* <p>
* This is the value of the From header of recieved responses in this
* dialog when acting as an User Agent Server.
*
*@return the address object of the remote party.
*/
GetRemoteParty() address.Address
/**
* Returns the Address identifying the remote target. This is the value of
* the Contact header of recieved Responses for Requests or refresh Requests
* in this dialog when acting as an User Agent Client.
* <p>
* This is the value of the Contact header of recieved Requests or refresh
* Requests in this dialog when acting as an User Agent Server.
*
* @return the address object of the remote target.
*/
GetRemoteTarget() address.Address
/**
* Get the dialog identifer of this dialog. A dialog Id is
* associated with all responses and with any request that contains a tag
* in the To field. The rules for computing the dialog Id of a message
* depends on whether the SIP element is a User Agent Client or User Agent
* Server and applies to both requests and responses.
* <ul>
* <li>User Agent Client - the Call-Id value of the dialog Id is set to the
* Call-Id of the message, the remote tag is set to the tag in the To field
* of the message, and the local tag is set to the tag in the From field of
* the message.
* <li>User Agent Server - the Call-Id value of the dialog Id is set to the
* Call-Id of the message, the remote tag is set to the tag in the From
* field of the message, and the local tag is set to the tag in the To
* field of the message.
* </ul>
*
* @return the string identifier for this dialog.
*/
GetDialogId() string
/**
* Returns the Call-Id for this SipSession. This is the value of the
* Call-Id header for all messages belonging to this session.
*
* @return the Call-Id for this dialog
*/
GetCallId() header.CallIdHeader
/**
* The local sequence number is used to order requests from this
* User Agent Client to its peer User Agent Server. The local sequence
* number MUST be set to the value of the sequence number in the CSeq
* header field of the request. The remote sequence number MUST be empty as
* it is established when the remote User Agent sends a request within the
* dialog.
* <p>
* Requests within a dialog MUST contain strictly monotonically increasing
* and contiguous CSeq sequence numbers (increasing-by-one) in each
* direction (excepting ACK and CANCEL, whose numbers equal the requests
* being acknowledged or cancelled). Therefore, if the local sequence number
* is not empty, the value of the local sequence number MUST be incremented
* by one, and this value MUST be placed into the CSeq header field. If the
* local sequence number is empty, an initial value MUST be chosen.
*
*@return the integer value of the local sequence number, returns zero if
* not set.
*/
GetLocalSequenceNumber() int
/**
* The remote sequence number is used to order requests from its
* peer User Agent Client to this User Agent Server. When acting an User
* Agent Server the remote sequence number MUST be set to the value of the
* sequence number in the CSeq header field of the request from the User
* Agent Client. The local sequence number MUST be empty.
* <p>
* If the remote sequence number is empty, it MUST be set to the value of
* the sequence number in the CSeq header field value in the request. If
* the remote sequence number was not empty, but the sequence number of the
* request is lower than the remote sequence number, the request is out of
* order and MUST be rejected with a 500 (Server Internal Error) response.
* If the remote sequence number was not empty, and the sequence number of
* the request is greater than the remote sequence number, the request is
* in order.
*
*@return the integer value of the remote sequence number, return zero if
* not set.
*/
GetRemoteSequenceNumber() int
/**
* When acting as an User Agent Server
* the routeset MUST be set to the list of URIs in the Record-Route header
* field from the request, taken in order and preserving all URI parameters.
* When acting as an User Agent Client the route set MUST be set to the list
* of URIs in the Record-Route header field from the response, taken in
* reverse order and preserving all URI parameters. If no Record-Route
* header field is present in the request or response, the route set MUST
* be set to the empty set. This route set, even if empty, overrides any
* pre-existing route set for future requests in this dialog.
* <p>
* Requests within a dialog MAY contain Record-Route and Contact header
* fields. However, these requests do not cause the dialog's route set to be
* modified.
* <p>
* The User Agent Client uses the remote target and route set to build the
* Request-URI and Route header field of the request.
*
* @return an Iterator containing a list of route headers to be used for
* forwarding.
*/
GetRouteSet() *list.List //Iterator;
/**
* Returns true if this Dialog is secure i.e. if the request was sent over
* a "sips:" scheme, or a "sip:" scheme over TLS.
*
* @return <code>true</code> if this dialog was secure, and
* <code>false</code> otherwise.
*/
IsSecure() bool
/**
* Returns whether this Dialog is a server dialog. A proxy may wish to keep
* an associated sets of dialogs for forking, i.e. a single server dialog is
* associated with multiple client dialogs.
*
* @return <code>true</code> if this is a server dialog and <code>false</code>
* if it is a client dialog.
*/
IsServer() bool
/**
* This method may be used to increment the local sequence number of the
* dialog when an application wishes to switch from dialog stateful mode
* to transaction stateful mode for client transactions and back again
* to dialog stateful mode. Note, the Dialog layer automatically
* increments the local sequence number when a request is sent out via
* the Dialog. However in special circumstances applications may wish to
* send a request (from a sequence of dialog requests) outside of the
* Dialog using the {@link ClientTransaction#sendRequest()} method. When sending
* a request using the Transaction the Dialog state is unaffected.
*/
IncrementLocalSequenceNumber()
/**
* Creates a new Request message based on the dialog creating request.
* This method should be used for but not limited to creating Bye's,
* Refer's and re-Invite's on the Dialog. The returned Request will be
* correctly formatted that is the Dialog implementation is responsible
* for assigning the following:
* <ul>
* <li> RequestURI
* <li> FromHeader
* <li> ToHeader
* <li> CallIdHeader
* <li> RouteHeaders
* </ul>
* The CSeqHeader will be set when the message is sent. If this method
* returns a CSeqHeader in the Request it may be overwritten again by
* the {@link Dialog#sendRequest(ClientTransaction)} method. Therefore
* any Request created by this method must be sent via the
* {@link Dialog#sendRequest(ClientTransaction)} method and not via its
* {@link ClientTransaction#sendRequest()} method.
* <p>
* All other headers including any Authentication related headers, and
* record route headers should be assigned by the application to the
* generated request. The assignment of the topmost via header for the
* outgoing request may be deferred until the application creates a
* ClientTransaction to send the request out. This method does not
* increment the dialog sequence number.
*
* @param method the string value that determines if the request to be
* created.
* @return the newly created Request message on this Dialog.
* @throws SipException if the Dialog is not yet established (i.e.
* dialog state equals null) or is terminated.
*/
CreateRequest(method string) (r message.Request, SipException error)
/**
* Sends a Request to the remote party of this dialog. When an application
* wishes to send a Request message on this dialog, it creates a Request
* and creates a new ClientTransaction to handle this request from
* {@link SipProvider#getNewClientTransaction(Request)}. This
* ClientTransaction is passed to this method to send the request. The Request
* message gets sent via the ListeningPoint information of the SipProvider
* that is associated to this ClientTransaction.
*<p>
* This method implies that the application is functioning as UAC hence the
* underlying SipProvider acts statefully. This method is useful for
* sending Bye's to terminate a dialog or Re-Invites/Refers on the
* Dialog for third party call control, call hold etc.
* <p>
* This methods will set the From and the To tags for the outgoing
* request. This method increments the dialog sequence number and sets
* the correct sequence number to the outgoing Request and associates
* the client transaction with this dialog.
* Note that any tags assigned by the user will be over-written by this
* method. If the caller sets no RouteHeader in the Request to be sent out,
* the implementation of this method will add the RouteHeader from the
* routes that are mantained in the dialog. If the caller sets the
* RouteHeader's, the implementation will leave the route headers
* unaltered. This allows the application to manage its own route set if
* so desired.
* <p>
* The User Agent traditionally must not send a BYE on a confirmed INVITE until it has
* received an ACK for its 2xx response or until the server transaction
* timeout is received.
* <p>
* When the {@link SipStack#isRetransmissionFilterActive()} is <code>true</code>,
* that is the SipProvider takes care of all retransmissions for the
* application, and the SipProvider can not deliver the Request after
* multiple retransmits the SipListener will be notified with a
* {@link TimeoutEvent} when the transaction expires.
*
* @param clientTransaction - the new ClientTransaction object identifying
* this transaction, this clientTransaction should be requested from
* {@link SipProvider#getNewClientTransaction(Request)}
* @throws TransactionDoesNotExistException if the clientTransaction does
* not correspond to any existing client transaction.
* @throws SipException if implementation cannot send the Request for
* any reason.
*/
SendRequest(clientTransaction ClientTransaction) (SipException error)
/**
* Sends ACK Request to the remote party of this dialog. This method
* implies that the application is functioning as User Agent Client hence
* the underlying SipProvider acts statefully. This method does not
* increment the local sequence number.
*
* @param ackRequest - the new ACK Request message to send.
* @throws SipException if implementation cannot send the ACK Request for
* any reason
*/
SendAck(ackRequest message.Request) (SipException error)
/**
* Returns the current state of the dialog. A dialog that is created but
* not yet mapped to any state must return null, multiple requests can be
* generated on the Dialog in a null state, e.g. pseudo dialog's. The
* dialog states are:
* <ul>
* <li> Early - A dialog is in the "early" state, which occurs when it is
* created when a provisional response is recieved to the INVITE Request.
* <li> Confirmed - A dialog transitions to the "confirmed" state when a 2xx
* final response is received to the INVITE Request.
* <li> Completed - A dialog transitions to the "completed" state when a BYE
* request is sent or received by the User Agent Client.
* <li> Terminated - A dialog transitions to the "terminated" state when it
* can be garbage collection.
* </ul>
* Independent of the method, if a request outside of a dialog generates a
* non-2xx final response, any early dialogs created through provisional
* responses to that request are "terminated". If no response arrives at all
* on the early dialog it is also "terminated".
*
* @return a DialogState determining the current state of the dialog.
* @see DialogState
*/
GetState() *DialogState
/**
* This method will release all resources associated with this dialog
* that are tracked by the SipProvider. Further references to the dialog by
* incoming messages will result in a mismatch. This delete method is provided
* for future use and extension methods that do not require a BYE to
* terminate a dialog. The basic case of the INVITE and all dialogs
* that we are aware of today it is expected that BYE requests will end the
* dialog.
*/
Delete()
/**
* This method retrieves the transaction which resulted in the creation of
* this Dialog. The transaction type either server or client can be determined
* based on whether this is a server or client Dialog, see
* {@link Dialog#isServer()}.
*
* @return the Transaction that created the Dialog.
*/
GetFirstTransaction() Transaction
/**
* Get the Local Tag of this Dialog. On the client side, this tag is
* assigned to outgoing From headers for Requests within the dialog and
* To headers for responses within the dialog. On the server side, this
* tag is associated with outgoing To headers for responses within the
* dialog.
*/
GetLocalTag() string
/**
* Gets the Remote Tag of this Dialog. On the client side, this tag is
* associated with outgoing To headers for Requests within the dialog. On
* the server side, this tag is associated with incoming From headers for
* requests within the dialog.
*/
GetRemoteTag() string
/**
* Sets application specific data to this dialog. This specification
* does not define the format of this data. This is the responsibility
* of the application and is dependent upon the application. This method
* can be used to link the call state of this dialog to other state, SIP
* or otherwise in the system. For example this method could be used by
* a SIP-to-H323 interworking node that would associate the H323 call state
* associated with a call on the H323 side with this dialog that
* represents this call on the SIP side. Or a dialog stateful proxy can
* associate the UAS dialog to the UAC dialog and vice versa.
*
* @param applicationData the new object containing application specific
* data.
*/
SetApplicationData(applicationData interface{})
/**
* Gets the application specific data specific to this dialog. This
* specification does not define the format of this application specific
* data. This is the responsibility of the application.
*
* @return the object representation of the application specific data.
*/
GetApplicationData() interface{}
}
type DialogState ¶
type DialogState struct {
// contains filtered or unexported fields
}
func GetDialogState ¶
func GetDialogState(dialogState int) (*DialogState, error)
*
- This method returns the object value of the DialogState *
- @return The DialogState Object
- @param timeout The integer value of the DialogState
func (*DialogState) GetValue ¶
func (this *DialogState) GetValue() int
*
- This method returns the integer value of the DialogState *
- @return The integer value of the DialogState
func (*DialogState) ToString ¶
func (this *DialogState) ToString() string
*
- This method returns a string version of this class.
- @return The string version of the DialogState
type ListeningPoint ¶
type ListeningPoint interface {
/**
* Gets the port of the ListeningPoint. The default port of a ListeningPoint
* is dependent on the scheme and transport. For example:
* <ul>
* <li>The default port is 5060, if the transport UDP and the scheme is
* <i>sip:</i>.
* <li>The default port is 5060, if the transport is TCP and the scheme
* is <i>sip:</i>.
* <li>The default port is 5060, if the transport is SCTP and the scheme
* is <i>sip:</i>.
* <li>The default port is 5061, if the transport is TLS over TCP and the
* scheme is <i>sip:</i>.
* <li>The default port is 5061, if the transport is TCP and the scheme
* is <i>sips:</i>.
* </ul>
*
* @return the integer value of the port.
*/
GetPort() int
/**
* Gets the transport of the ListeningPoint.
*
* @return the string value of the transport.
*/
GetTransport() string
/**
* This method indicates whether the specified object is equal to this
* Listening Point. The specified object is equal to this ListeningPoint
* if the specified object is a ListeningPoint and the transport and port
* in the specified Listening Point is the same as this Listening Point.
*
* @param obj - the object with which to compare this ListeningPoint.
* @return true if this ListeningPoint is "equal to" the obj argument;
* false otherwise.
*/
Equals(obj interface{}) bool
}
type RequestEvent ¶
type RequestEvent struct {
// contains filtered or unexported fields
}
*
- This class represents an Request event that is passed from a SipProvider to
- its SipListener. This specification handles the passing of request messages to the
- application use the event model. An application (SipListener) will register
- with the SIP protocol stack (SipProvider) and listen for Request events
- from the SipProvider.
- <p>
- This specification defines a single Request event object to handle all Request
- messages. The Request event encapsulates the Request message that can be
- retrieved from {@link RequestEvent#getRequest()}. Therefore the event type
- of a Request event can be determined as follows:
- <p>
- <i>eventType == RequestEvent.getRequest().getMethod();</i>
- <p>
- A Request event also encapsulates the server transaction which handles the
- Request.
- <p>
- RequestEvent contains the following elements:
- <ul>
- <li>source - the source of the event i.e. the SipProvider sending the
- RequestEvent
- <li>serverTransaction - the server transaction this RequestEvent is
- associated with.
- <li>Request - the Request message received on the SipProvider
- that needs passed to the application encapsulated in a RequestEvent.
- </ul> *
- @author Sun Microsystems *
func (*RequestEvent) GetRequest ¶
func (this *RequestEvent) GetRequest() message.Request
*
- Gets the Request message associated with this RequestEvent. *
- @return the message associated with this RequestEvent.
func (*RequestEvent) GetServerTransaction ¶
func (this *RequestEvent) GetServerTransaction() ServerTransaction
*
- Gets the server transaction associated with this RequestEvent *
- @return the server transaction associated with this RequestEvent
type ResponseEvent ¶
type ResponseEvent struct {
// contains filtered or unexported fields
}
*
- This class represents a Response event that is passed from a SipProvider to
- its SipListener. This specification handles the passing of Response messages
- to the application with the event model. An application (SipListener)
- registers with the SIP protocol stack (SipProvider) and listens for Response
- events from the SipProvider.
- <p>
- This specification defines a single Response event object to handle all
- Response messages. The Response event encapsulates the Response message
- that can be retrieved from {@link javax.sip.ResponseEvent#getResponse()}.
- Therefore the event type of a Response event can be determined as follows:
- <p>
- <i>eventType == ResponseEvent.getResponse().getStatusCode();</i>
- <p>
- A Response event also encapsulates the client transaction upon which the
- Response is correlated, i.e. the client transaction of the Request
- message upon which this is a Response.
- <p>
- ResponseEvent contains the following elements:
- <ul>
- <li>source - the source of the event i.e. the SipProvider sending the
- ResponseEvent.
- <li>clientTransaction - the client transaction this ResponseEvent is
- associated with.
- <li>Response - the Response message received on the SipProvider
- that needs passed to the application encapsulated in a ResponseEvent.
- </ul> *
- @author Sun Microsystems *
func (*ResponseEvent) GetClientTransaction ¶
func (this *ResponseEvent) GetClientTransaction() ClientTransaction
*
- Gets the client transaction associated with this ResponseEvent *
- @return client transaction associated with this ResponseEvent
func (*ResponseEvent) GetResponse ¶
func (this *ResponseEvent) GetResponse() message.Response
*
- Gets the Response message encapsulated in this ResponseEvent. *
- @return the response associated with this ResponseEvent.
type ServerTransaction ¶
type ServerTransaction interface {
Transaction
/**
* Sends the Response to a Request which is identified by this
* ServerTransaction. When an application wishes to send a Response, it
* creates a Response from the {@link javax.sip.message.MessageFactory} and
* then passes that Response to this method. The Response message gets sent out on
* the network via the ListeningPoint information that is associated to
* the SipProvider of this ServerTransaction.
* <p>
* This method implies that the application is functioning as either a UAS
* or a stateful proxy, hence the underlying implementation acts statefully.
* When a UAS sends a 2xx response to an INVITE, the server transaction is
* destroyed, by the underlying implementation. This means that
* when the ACK sent by the corresponding UAC arrives at the UAS, there will
* be no matching server transaction for the ACK, and based on this rule,
* the ACK is passed to the UAS application, where it is processed. This
* ensures that the three way handsake of an INVITE is managed by the UAS
* application and not the implementation. However when the
* {@link SipStack#isRetransmissionFilterActive()} is turned ON for User Agent's
* the implementation will take care of this behaviour for the application and
* notify the application of an error with a {@link Timeout#TRANSACTION}
* Event.
*
* @param response the Response to send to the Request.
* @throws SipException if the SipProvider cannot send the Response for any
* other reason.
* @see Response
*/
SendResponse(response message.Response) (SipException error)
}
*
- A server transaction is used by a SipProvider to handle incoming Request
- messages to fire Request events to the SipListener on a specific server
- transaction and by a User Agent Server application to send Response
- messages to a User Agent Client application. This interfaces enables an
- application to send a {@link javax.sip.message.Response} to a recently
- received Request statefully.
- <p>
- A new server transaction is generated in the following ways:
- <ul>
- <li> By the application by invoking the
- {@link SipProvider#getNewServerTransaction(Request)} for Dialog-Creating
- Requests that the application wishes to handle.
- <li> By the SipProvider by automatically populating the server transaction
- of a RequestEvent for Incoming Requests in an existing Dialog handled by
- the application.
- </ul>
- A server transaction of the transaction layer is represented by a finite
- state machine that is constructed to process a particular request under
- the covers of a stateful SipProvider. The transaction layer handles
- application-layer retransmissions, matching of responses to requests, and
- application-layer timeouts.
- <p>
- The server transaction must be unique within the underlying
- implementation. A common way to create this value is to compute a
- cryptographic hash of the To tag, From tag, Call-ID header field, the
- Request-URI of the request received (before translation), the topmost Via
- header, and the sequence number from the CSeq header field, in addition to
- any Proxy-Require and Proxy-Authorization header fields that may be present.
- The algorithm used to compute the hash is implementation-dependent.
- <p>
- For the detailed server transaction state machines refer to Chapter
- 17 of <a href="http://www.ietf.org/rfc/rfc3261.txt">RFC 3261</a>, the
- allowable transitions are summarized below:
- <p>
- <b>Invite Transaction:</b><br>
- Proceeding --> Completed --> Confirmed --> Terminated
- <p>
- <b>Non-Invite Transaction:</b><br>
- Trying --> Proceeding --> Completed --> Terminated *
- @author Sun Microsystems *
type SipListener ¶
type SipListener interface {
/**
* Processes a Request received on a SipProvider upon which this SipListener
* is registered.
* <p>
* <b>Handling Requests:</b><br>
* When the application receives a RequestEvent from the SipProvider the
* RequestEvent may or may not belong to an existing dialog of the application.
* The application can be determine if the RequestEvent belongs to an
* existing dialog by checking the server transaction of the RequestEvent.
* <ul>
* <li>If the server transaction equals <code>null</code> the RequestEvent does
* not belong to an existing dialog and the application must determine how
* to handle the RequestEvent. If the application decides to forward the
* Request statelessly no transactional support is required and it can simply
* pass the Request of the RequestEvent as an argument to the
* {@link SipProvider#sendRequest(Request)} method. However if the
* application determines to respond to a Request statefully it must request
* a new server transaction from the
* {@link SipProvider#getNewServerTransaction(Request)} method and use this
* server transaction to send the Response based on the content of the Request.
* If the SipProvider throws TransactionAlreadyExistsException when the
* application requests a new server transaction to handle a Request the
* current RequestEvent is a retransmission of the initial request from which
* the application hadn't requested a server transaction to handle it, i.e.
* this exception handles the race condition of an application informing the
* SipProvider that it will handle a Request and the receipt of a
* retransmission of the Request from the network to the SipProvider.
* <li>If the server transaction <b>does NOT</b> equal <code>null</code> the
* application determines its action to the RequestEvent based on the
* content of the Request information.
* </ul>
* <p>
* <b>User Agent Server (UAS) Behaviour:</b><br>
* A UAS application decides whether to accept the an invitation from a
* UAC. The UAS application can accept the invitation by sending a 2xx
* response to the UAC, a 2xx response to an INVITE transaction establishes
* a session. For 2xx responses, the processing is done by the UAS
* application, to guarantee the three way handshake of an INVITE
* transaction. This specification defines a utility thats enables the
* SipProvider to handle the 2XX processing for an INVITE transaction, see
* the {@link SipStack#isRetransmissionFilterActive()} method. If the
* invitation is not accepted, a 3xx, 4xx, 5xx or 6xx response is sent by
* the application, depending on the reason for
* the rejection. Alternatively before sending a final response, the UAS
* can also send provisional responses (1xx) to advise the UAC of progress
* in contacting the called user. A UAS that receives a CANCEL request for
* an INVITE, but has not yet sent a final response, would "stop ringing"
* and then respond to the INVITE with a specific 487 Error response.
* <p>
* <b>General Proxy behaviour:</b><br>
* In some circumstances, a proxy application MAY forward requests using
* stateful transports without being transaction stateful,
* i.e. using the {@link SipProvider#sendRequest(Request)} method,
* but using TCP as a transport. For example, a proxy application MAY
* forward a request from one TCP connection to another transaction
* statelessly as long as it places enough information in the message to be
* able to forward the response down the same connection the request arrived
* on. This is the responsibility of the application and not the SipProvider.
* Requests forwarded between different types of transports where the
* proxy application takes an active role in ensuring reliable delivery on
* one of the transports must be forwarded using the stateful send methods
* on the SipProvider.
* <p>
* <b>Stateful Proxies:</b><br>
* A stateful proxy MUST create a new server transaction for each new
* request received, either automatically generated by the SipProvider,
* if the request matches an existing dialog or by the an
* application call on the SipProvider if it decides to respond to the
* request statefully. The proxy application determines where to
* route the request, choosing one or more next-hop locations. An outgoing
* request for each next-hop location is processed by its own associated
* client transaction. The proxy application collects the responses from
* the client transactions and uses them to send responses to the server
* transaction. When an application receives a CANCEL request that matches
* a server transaction, a stateful proxy cancels any pending client
* transactions associated with a response context. A stateful proxy
* responds to the CANCEL rather than simply forwarding a response it would
* receive from a downstream element.
* <p>
* For all new Requests, including any with unknown methods, an element
* intending to stateful proxy the Request determines the target(s) of the
* request. A stateful proxy MAY process the targets in any order.
* A stateful proxy must have a mechanism to maintain the target set as
* responses are received and associate the responses to each forwarded
* request with the original request. For each target, the proxy forwards
* the request following these steps:
* <ul>
* <li>Make a copy of the received request.
* <li>Update the Request-URI.
* <li>Update the Max-Forwards header.
* <li>Optionally add a Record-route header.
* <li>Optionally add additional headers.
* <li>Postprocess routing information.
* <li>Determine the next-hop address, port, and transport.
* <li>Add a Via header.
* <li>Add a Content-Length header if necessary.
* <li>Forward the new request using the
* {@link ClientTransaction#sendRequest()} method.
* <li>Process all responses recieved on the
* {@link SipListener#processResponse(ResponseEvent)} method.
* <li>NOT generate 100 (Trying) responses to non-INVITE requests.
* </ul>
* <p>
* A stateful proxy MAY transition to stateless operation at any time
* during the processing of a request, as long as it did nothing that
* would prevent it from being stateless initially i.e. forking or
* generation of a 100 response. When performing such a transition, any
* state already stored is simply discarded.
* <p>
* <b>Forking Requests:</b><br>
* A stateful proxy application MAY choose to "fork" a request, routing it
* to multiple destinations. Any request that is forwarded to more than
* one location MUST be forwarded using the stateful send methods on the
* SipProvider.
* <p>
* <b>Stateless Proxies:</b><br>
* As a stateless proxy does not have any notion of a transaction, or of
* the response context used to describe stateful proxy behavior,
* <code>requestEvent.getServerTransaction() == null;</code>
* always return <var>true</var>. The transaction layer of the SipProvider
* implementation is by-passed. For all requests including any with
* unknown methods, an application intending to stateless proxy the request
* MUST:
* <ul>
* <li>Validate the request.
* <li>Preprocess routing information.
* <li>Determine a single target(s) for the request.
* <li>Forward the request to the target using the
* {@link SipProvider#sendRequest(Request)} method.
* <li>NOT perform special processing for CANCEL requests.
* </ul>
*
*
* @param requestEvent - requestEvent fired from the SipProvider to
* the SipListener representing a Request received from the network.
*/
ProcessRequest(requestEvent RequestEvent)
/**
* Processes a Response received on a SipProvider upon which this
* SipListener is registered.
* <p>
* <b>Handling Responses:</b><br>
* When the application receives a ResponseEvent from the SipProvider the
* ResponseEvent may or may not correlate to an existing Request of the
* application. The application can be determine if the ResponseEvent belongs
* to an existing Request by checking the client transaction of the
* ResponseEvent.
* <ul>
* <li>If the the client transaction equals <code>null</code> the
* ResponseEvent does not belong to an existing Request and the Response is
* considered stray, i.e. stray response can be identitied, if
* <code>responseEvent.getClientTransaction() == null;</code>. Handling of
* these "stray" responses is dependent on the application i.e. a proxy will
* forward them statelessly using the
* {@link SipProvider#sendResponse(Response)} method, while a User
* Agent will discard them.
* <li>If the client transaction <b>does NOT</b> equal <code>null</code> the
* application determines it action to the ResponseEvent based on the
* content of the Response information.
* </ul>
* <p>
* <b>User Agent Client (UAC) behaviour:</b><br>
* After possibly receiving one or more provisional responses (1xx) to a
* Request, the UAC will get one or more 2xx responses or one non-2xx final
* response. Because of the protracted amount of time it can take to receive
* final responses to an INVITE, the reliability mechanisms for INVITE
* transactions differ from those of other requests.
* A UAC needs to send an ACK for every final Response it receives, however
* the procedure for sending the ACK depends on the type of Response. For
* final responses between 300 and 699, the ACK processing is done by the
* transaction layer i.e. handled by the implementation. For 2xx responses, the
* ACK processing is done by the UAC application, to guarantee the three way
* handshake of an INVITE transaction. This specification defines a utility
* thats enables the SipProvider to handle the ACK processing for an INVITE
* transaction, see the {@link SipStack#isRetransmissionFilterActive()} method.
* <br>
* A 2xx response to an INVITE establishes a session, and it also
* creates a dialog between the UAC that issued the INVITE and the UAS
* that generated the 2xx response. Therefore, when multiple 2xx responses
* are received from different remote User Agents, i.e. the INVITE forked,
* each 2xx establishes a different dialog and all these dialogs are part of
* the same call. If an INVITE client transaction returns a {@link TimeoutEvent}
* rather than a response the UAC acts as if a 408 (Request Timeout)
* response had been received from the UAS.
* <p>
* <b>Stateful Proxies:</b><br>
* A proxy application that handles a response statefully must do the
* following processing:
* <ul>
* <li>Find the appropriate response context.
* <li>Remove the topmost Via header.
* <li>Add the response to the response context.
* <li>Check to determine if this response should be forwarded immediately.
* <li>When necessary, choose the best final response from the
* response context. If no final response has been forwarded after every
* client transaction associated with the response context has been
* terminated, the proxy must choose and forward the "best" response
* from those it has seen so far.
* </ul>
* <p>
* Additionally the following processing MUST be performed on each response
* that is forwarded.
* <ul>
* <li>Aggregate authorization header values if necessary.
* <li>Optionally rewrite Record-Route header values.
* <li>Forward the response using the
* {@link ServerTransaction#sendResponse(Response)} method.
* <li>Generate any necessary CANCEL requests.
* </ul>
* <p>
* <b>Stateless Proxies:</b><br>
* As a stateless proxy does not have any notion of transactions, or of
* the response context used to describe stateful proxy behavior,
* <code>responseEvent.getClientTransaction == null;</code>
* always return <var>true</var>. Response processing does not apply, the
* transaction layer of the SipProvider implementation is by-passed. An
* application intending to stateless proxy the Response MUST:
* <ul>
* <li>Inspect the sent-by value in the first Via header.
* <li>If that address matches the proxy, the proxy MUST remove that header
* from the response.
* <li>Forward the resulting response to the location indicated in the
* next Via header using the
* {@link SipProvider#sendResponse(Response)} method.
* </ul>
*
*
* @param responseEvent - the responseEvent fired from the SipProvider to
* the SipListener representing a Response received from the network.
*/
ProcessResponse(responseEvent ResponseEvent)
/**
* Processes a retransmit or expiration Timeout of an underlying
* {@link Transaction} handled by this SipListener. This Event notifies the
* application that a retransmission or transaction Timer expired in the
* SipProvider's transaction state machine. The TimeoutEvent encapsulates
* the specific timeout type and the transaction identifier either client
* or server upon which the timeout occured. The type of Timeout can by
* determined by:
* <code>timeoutType = timeoutEvent.getTimeout().getValue();</code>
*
* @param timeoutEvent - the timeoutEvent received indicating either the
* message retransmit or transaction timed out.
*/
ProcessTimeout(timeoutEvent TimeoutEvent)
}
*
- This interface represents the application view to a SIP stack
- therefore defines the application's communication channel to the SIP stack.
- This interface defines the methods required by an applications to receive
- and process Events that are emitted by an object implementing the
- {@link javax.sip.SipProvider} interface.
- <p>
- The Events accepted by a SipListener may be one of three types:
- <ul>
- <li> {@link RequestEvent} - these are request messages emitted
- as events by the SipProvider. Request events represent
- request messages i.e. INVITE, that are received from the network to the
- application via the underlying stack implementation.
- <li> {@link ResponseEvent} - these are response messages emitted
- as events by the SipProvider. Response events represent
- Response messages i.e. 2XX's, that are received from the network to the
- application via the underlying stack implementation.
- <li> {@link TimeoutEvent} - these are timeout notifications
- emitted as events by the SipProvider. Timeout events represent
- timers expiring in the underlying SipProvider transaction state machine.
- These timeout's events notify the application that a retranmission is
- required or a transaction has timed out.
- </ul>
- <p>
- An application will only receive Request, Response and Timeout
- events once it has registered as an EventListener of a SipProvider.
- The application registers with the SipProvider by invoking the
- {@link SipProvider#addSipListener(SipListener)} passing itself as an argument.
- <p>
- <b>Architecture:</b><br>
- This specification mandates a single SipListener per SipStack/per IP Address,
- and a unicast event model i.e. a SipProvider can only have one SipListener
- registered with it. This specification allows multiple SipProviders per
- SipStack and as such a SipListener can register with multiple SipProviders
- i.e there is a one-to-many relationship between a SipListener and a
- SipProvider.
- <p>
- Note: An application that implements the SipListener interface, may act as a
- proxy object and pass all events to higher level core application
- programming logic that is outside the scope of this specification. For
- example a SIP Servlet, JAIN SLEE or an EJB SIP implementation can implement
- the UAS, UAC and Proxy core application respectively in there respective
- container environments utilizing this specification to talk to the
- SIP network.
- <p>
- <b>Messaging Model:</b><br>
- An application can send messages by passing
- {@link javax.sip.message.Request} and {@link javax.sip.message.Response}
- messages to that the following object:
- <ul>
- <li>Request and response messages can be sent statelessly via the
- SipProvider using the sendXXX methods on the {@link javax.sip.SipProvider}.
- <li>Request messages can be sent transaction stateful via the
- ClientTransaction using the
- {@link ClientTransaction#sendRequest()} method.
- <li>Response messages can be sent transaction stateful via the
- ServerTransaction using the
- {@link ServerTransaction#sendResponse(Response)} method.
- <li>Request messages can be sent dialog stateful via the
- Dialog using the
- {@link Dialog#sendRequest(ClientTransaction)} method.
- </ul>
- Although this specification provides the capabilities to send messages both
- statelessly and statefully it is mandated that an application will not send
- the same message both statefully and statelessly.<br>
- The messages sent by the application are not Event's as the event model is
- uni-directional from the SipProvider to the SipListener, i.e. the
- SipListener listens for Events from the SipProvider, but the SipProvider does
- not listen for Events on the SipListener. The rationale is the application
- knows when to initiate requests and responses i.e setup a call or respond to
- a network event, however an application doesn't know when it will receive a
- network event, hence the application must listen for these network events.
- The traditional way to do this in Java is the Java event model.
- <p>
- <b>Session Negotiation</b><br>
- There are special rules for message bodies of Request and Responses that
- contain a session description. SIP uses an offer/answer model where one User
- Agent sends a session description, called the offer, which contains a proposed
- description of the session. The other User Agent responds with another session
- description, called the answer, which indicates which communications means
- are accepted. In this specification, offers and answers can only appear in
- INVITE requests and Responses, and ACK. The Session Description Protocol (SDP)
- <a href = "http://www.ietf.org/rfc/rfc2327.txt">RFC2327</a> MUST be
- supported by all user agents as a means to describe sessions, and its usage
- for constructing offers and answers MUST follow the procedures defined in
- <a href = "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a>. The SDP protocol
- is described in Java by
- <a href = "http://www.jcp.org/en/jsr/detail?id=141">JSR 141</a> *
- @see SipProvider
- @see RequestEvent
- @see ResponseEvent
- @see TimeoutEvent *
- @author Sun Microsystems
- @version 1.1
type SipProvider ¶
type SipProvider interface {
/**
* This method registers the SipListener object to this SipProvider, once
* registered the SIP Listener recieve events emitted from the SipProvider.
* This specification restricts a unicast Listener model, that is only one
* Listener may be registered on the SipProvider concurrently. If an
* attempt is made to re-register the existing registered SipListener this
* method returns silently, however a SipListener must be removed from the
* SipProvider before a different SipListener can be registered to the
* SipProvider.
*
* @param sipListener the SipListener to be registered with the SipProvider.
* @throws TooManyListenersException when a new SipListener attempts to
* register with the SipProvider when another SipListener is already
* registered with this SipProvider.
*/
AddSipListener(sipListener SipListener) (TooManyListenersException error)
/**
* Removes the specified SipListener from this SipProvider. This method
* returns silently if the SipListener is not registered with the SipProvider.
*
* @param SipListener the SipListener to be removed from this SipProvider.
*/
RemoveSipListener(sipListener SipListener)
/**
* Returns the SipStack that created this SipProvider. A SipProvider
* can only be attached to a single SipStack object that belongs to the same
* implementation as this SipProvider.
*
* @see SipStack
* @return the SipStack that created this SipProvider.
*/
GetSipStack() SipStack
/**
* Returns the ListeningPoint of this SipProvider. A SipProvider has a single
* Listening Point at any specific point in time.
*
* @see ListeningPoint
* @return the ListeningPoint of this SipProvider.
*/
GetListeningPoint() ListeningPoint
/**
* This method sets the ListeningPoint of the SipProvider. A SipProvider can
* only have a single ListeningPoint at any specific time, i.e. multiple
* SipProviders are prohibited to listen on the same ListeningPoint. This
* method returns silently if the same ListeningPoint argument is re-set on
* the SipProvider.
*
* @param listeningPoint the ListeningPoint of this SipProvider.
* @throws ObjectInUseException when an application invokes this method
* with a ListeningPoint that is being used by another SipProvider in the
* system.
* @see ListeningPoint
*
*/
SetListeningPoint(listeningPoint ListeningPoint) (ObjectInUseException error)
/**
* Returns a unique CallIdHeader for identifying dialogues between two
* SIP applications.
*
* @return the new CallIdHeader unique within the SipProvider.
*/
GetNewCallId() header.CallIdHeader
/**
* Before an application can send a new request it must first request
* a new client transaction to handle that Request. This method is called
* by the application to create the new client transaction befores it sends
* the Request on that transaction. This methods returns
* a new unique client transaction that can be passed to send Requests
* statefully.
*
* @param request the new Request message that is to handled statefully by
* the ClientTransaction.
* @return a new unique client transaction.
* @throws TransactionUnavailableException if a new transaction can not be created, for example
* the next hop of the request can not be determined.
* @see ClientTransaction
*
*/
GetNewClientTransaction(request message.Request) (ct ClientTransaction, TransactionUnavailableException error)
/**
* An application has the responsibility of deciding to respond to a
* Request that does not match an existing server transaction. This method
* is called by an application that decides to respond to an unmatched
* Request statefully. This methods return a new unique server transaction
* that can be used to respond to the request statefully.
*
* @param request the Request message that the doesn't match an existing
* transaction that the application decides to handle statefully.
* @return a new unique server transaction.
* @throws TransactionAlreadyExistsException if a transaction already exists
* that is already handling this Request. This may happen if the application
* gets retransmits of the same request before the initial transaction is
* allocated.
* @throws TransactionUnavailableException if a new transaction can not be created, for example
* the next hop of the request can not be determined.
* @see ServerTransaction
*
*/
GetNewServerTransaction(request message.Request) (st ServerTransaction, TransactionException error)
/**
* Sends the Request statelessly, that is no transaction record is
* associated with this action. This method implies that the application is
* functioning as a stateless proxy, hence the underlying SipProvider acts
* statelessly. A stateless proxy simply forwards every request it receives
* downstream and discards information about the Request message once the
* message has been forwarded. A stateless proxy does not have any notion
* of a transaction.
* <p>
* Once the Request message has been passed to this method, the SipProvider
* will forget about this Request. No transaction semantics will be
* associated with the Request and the SipProvider will not handle
* retranmissions for the Request. If these semantics are required it is the
* responsibility of the application not the SipProvider.
*
*
* @see Request
* @param request the Request message to send statelessly
* @throws SipException if the SipProvider cannot send the Request for any
* reason.
*/
SendRequest(request message.Request) (SipException error)
/**
* Sends the Response statelessly, that is no transaction record is
* associated with this action. This method implies that the application is
* functioning as either a stateless proxy or a stateless UAS.
* <ul>
* <li> Stateless proxy - A stateless proxy simply forwards every response
* it receives upstream and discards information about the response message
* once the message has been forwarded. A stateless proxy does not
* have any notion of a transaction.
* <li>Stateless UAS - A stateless UAS does not maintain
* transaction state. It replies to requests normally, but discards
* any state that would ordinarily be retained by a UAS after a response
* has been sent. If a stateless UAS receives a retransmission of a
* request, it regenerates the response and resends it, just as if it
* were replying to the first instance of the request. A UAS cannot be
* stateless unless the request processing for that method would always
* result in the same response if the requests are identical. Stateless
* UAS's do not use a transaction layer; they receive requests directly
* from the transport layer and send responses directly to the transport
* layer.
* </ul>
*
* @see Response
* @param response the Response to send statelessly.
* @throws SipException if the SipProvider cannot send the Response for any
* reason.
* @see Response
*
*/
SendResponse(response message.Response) (SipException error)
}
*
- This interface represents the messaging entity of a SIP stack and as
- such is the interface that defines the messaging and transactional
- component view of the SIP stack. It must be implemented by any object
- representing a SIP stack compliant to this specification that interacts
- directly with a proprietary implementation of a SIP stack.
- This interface defines the methods that enable any registered
- application implementing the {@link javax.sip.SipListener} interface to:
- <ul>
- <li> Register a {@link javax.sip.SipListener} to the SipProvider. Once
- the SipListener is registered with the SipProvider it will get notified
- of Events representing either Request, Responce or Timeout messages.
- <li> De-register a {@link javax.sip.SipListener} from the SipProvider.
- Once a SipListener is de-registered, it will no longer receive any Events
- from that SipProvider.
- <li> Send {@link javax.sip.message.Request}'s statelessly.
- <li> Send {@link javax.sip.message.Response}'s statelessly.
- <li> Client and Server Transaction creation methods.
- <li> Listening Point manipulation methods.
- <li> New CallIdHeader accessor method.
- <li> SipStack object accessor method.
- </ul>
- <p>
- <b>Architecture:</b><br>
- This specification defines a many-to-one relationship between a SipProvider
- and a SipStack, a one-to-one relationship between a SipProvider and a
- ListeningPoint and a many-to-one relationship between a SipProvider
- and a SipListener.
- <p>
- A SipProvider has the capability to behave transaction statefully, dialog
- statefully and statelessly. The transaction stateful methods are defined
- on the ClientTransaction and ServerTransaction respectfully. The transaction
- stateful method defined specifically for UAC and stateful proxy
- applications is:
- <ul>
- <li> {@link ClientTransaction#sendRequest()}
- </ul>
- <p>
- The stateful (transactional) convenience method defined specifically for
- UAS and stateful proxy applications is:
- <ul>
- <li> {@link ServerTransaction#sendResponse(Response)}
- </ul>
- <p>
- The dialog stateful methods defined specifically for UAC and stateful
- proxy applications are:
- <ul>
- <li> {@link Dialog#sendRequest(ClientTransaction)}
- <li> {@link Dialog#sendAck(Request)}
- </ul>
- <p>
- The stateless methods (non-transactional) defined on the SipProvider
- are:
- <ul>
- <li> {@link SipProvider#sendResponse(Response)}
- <li> {@link SipProvider#sendRequest(Request)}
- </ul>
- <p>
- <b>Transaction Model:</b><br>
- This specification supports stateful and stateless applications on a per
- message basis, hence transactional semantics are not mandated for all
- messages. This specification defines two types of transactions, server
- transactions and client transactions. A stateless proxy does not contain a
- client or server transaction, stateless proxies are effectively transparent
- with respect to transactions.
- <p>
- Client Transaction:<br>
- A client transaction exists between a UAC and a UAS specific to Request
- messages and a server transaction exists between a UAS and a UAC specific
- to Response messages. A transaction either server or client identifies
- messages sent between two SIP entities. The purpose of a client transaction
- is to identify a Request sent by an application that will reliably deliver
- the Request to a server transaction on
- the responding SIP entity. The purpose of a server transaction is to
- identify a Response sent by an application that will reliably deliver the
- Response to the request initiator.
- <p>
- Server Transaction:<br>
- A new server transaction is required for each response that an application
- decides to respond to statefully, as follows:
- <ul>
- <li>Dialog-Creating Requests: A server transaction is not automatically
- generated by a SipProvider implementation upon receipt of every
- Dialog-Creating Request i.e. INVITE. Instead the
- server transaction is set to <code>null</code> in the RequestEvent and
- the RequestEvent also containing the Request is passed to the application.
- It is then the responsibility of the application to decide to handle the
- Dialog-Creating Request statefully or statelessly, using the appropriate
- send methods on the SipProvider and the ServerTransaction. If a retransmission of the initial Request
- request is recieved by the SipProvider the following procedures should be
- adhered to:
- <ul>
- <li>Determine if an exisiting transaction is already handling this Request.
- <li>If a transaction exists do not pass the Request to the application via a
- RequestEvent.
- <li>If a transaction doesn't exist pass the retransmitted request to the
- application as a RequestEvent.
- </ul>
- <li>Non-Dialog-Creating Requests - When the SipProvider receives a
- Non-Dialog-Creating Request upon which this application has already
- responded to the Dialog-Creating Request of the same dialogue the server
- transaction is automatically placed to the RequestEvent and passed up to
- the application upon which it can respond. Note that the server transaction
- may be null in a stateful implementation if the incoming request does not
- match any dialog but must be part of one. That is for requests that must
- have state but for which the stack cannot find that state, the application
- can still handle these requests statelessly. The application cannot create
- a new server transaction for such requests.
- </ul>
- <p>
- <b>Sending Requests:</b><br>
- The client side of the transport layer is responsible for sending the
- request. The application passes the the Request to the ClientTransaction
- Dialog or the SipProvider that will send the Request over the ListeningPoint's
- port and transport. See section 18.1.1 of
- <a href = "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a>.
- <p>
- <b>Sending Responses:</b><br>
- The server side of the transport layer is responsible for sending the
- responses. The application passes the Response to the ServerTransaction
- or the SipProvider that will send the Response over the ListeningPoint's port and transport.
- See section 18.2.2 of
- <a href = "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a>.
- <p>
- <b>Receiving Requests:</b><br>
- A SipProvider should be prepared to receive requests on any IP address,
- port and transport combination encapsulated in a ListeningPoint that can be
- the result of a DNS lookup on a SIP or SIPS URI that is handed out for the
- purposes of communicating with that server. It is also recommended that a
- SipProvider listen for requests on the default SIP ports on all public
- interfaces. When the SipProvider receives a request over any transport, it
- must examine the value of the "sent-by" parameter in the top Via
- header. If the host portion of the "sent-by" parameter contains a
- domain name, or if it contains an IP address that differs
- from the packet source address, the server must add a "received"
- parameter to that Via header field value. This parameter must
- contain the source address from which the packet was received. This
- is to assist the SipProvider in sending the response, since it must
- be sent to the source IP address from which the request came.
- Next, the SipProvider attempts to match the request to a server
- transaction. If there are any server transactions in existence, the server
- transport uses the matching procedures of Chapter 17 of
- <a href = "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a> to attempt to
- match the response to an existing transaction. If a matching server
- transaction is found, the request is passed to that transaction, encapsulated
- into a RequestEvent and fired to the application for processing. If no match
- is found, the request is passed to the application, which may decide to
- construct a new server transaction for that request.
- <p>
- <b>Receiving Responses</b><br>
- Responses are first processed by the transport layer and then passed
- up to the transaction layer. The transaction layer performs its
- processing and then passes the response up to the application.
- When a response is received, the SipProvider examines the top
- Via header. If the value of the "sent-by" parameter in that header field
- value does not correspond to a value that the client transport is configured
- to insert into requests, the response MUST be silently discarded. If there
- are any client transactions in existence, the client transport uses the
- matching procedures of Chapter 17 of
- <a href = "http://www.ietf.org/rfc/rfc3261.txt">RFC3261</a> to attempt to
- match the response to an existing transaction. If there is a
- match, the response must be passed to that transaction, encapsulated into a
- ResponseEvent and fired to the application. Otherwise, the response is stray
- and must be passed to the application to determine its outcome i.e. a proxy
- will forward them, while a User Agent will discard. *
- @see SipListener
- @see SipStack *
- @author Sun Microsystems
- @version 1.1
type SipStack ¶
type SipStack interface {
/**
* Creates a new peer SipProvider on this SipStack on a specified
* ListeningPoint and returns a reference to the newly created SipProvider
* object. The newly created SipProvider is implicitly attached to this
* SipStack upon execution of this method, by adding the SipProvider to the
* list of SipProviders of this SipStack once it has been successfully
* created.
*
* @return the SipProvider attached to this SipStack on the specified
* ListeningPoint.
* @param listeningPoint the ListeningPoint the SipProvider is to be
* attached to in order to send and receive messages.
* @throws ObjectInUseException if another SipProvider is
* already using the ListeningPoint.
*/
CreateSipProvider(listeningPoint ListeningPoint) (sp SipProvider, ObjectInUseException error)
/**
* Deletes the specified peer SipProvider attached to this SipStack. The
* specified SipProvider is implicitly detached from this SipStack upon
* execution of this method, by removing the SipProvider from the
* SipProviders list of this SipStack. Deletion of a SipProvider does not
* automatically delete the SipProvider's ListeningPoint from the SipStack.
*
* @param sipProvider the peer SipProvider to be deleted from this
* SipStack.
* @throws ObjectInUseException if the specified SipProvider cannot be
* deleted because the SipProvider is currently in use.
*
*/
DeleteSipProvider(sipProvider SipProvider) (ObjectInUseException error)
/**
* Returns an Iterator of existing SipProviders that have been
* created by this SipStack. All of the SipProviders of this SipStack will
* belong to the same stack vendor.
*
* @return an Iterator containing all existing SipProviders created
* by this SipStack. Returns an empty Iterator if no SipProviders exist.
*/
GetSipProviders() *list.List //Iterator
/**
* Creates a new ListeningPoint on this SipStack on a specified
* port and transport, and returns a reference to the newly created
* ListeningPoint object. The newly created ListeningPoint is implicitly
* attached to this SipStack upon execution of this method, by adding the
* ListeningPoint to the List of ListeningPoints of this SipStack once it
* has been successfully created.
*
* @return the ListeningPoint attached to this SipStack.
* @param port the port of the new ListeningPoint.
* @param transport the transport of the new ListeningPoint.
* @throws TansportNotSupportedException if the specified
* transport is not supported by this SipStack.
* @throws InvalidArgumentException if the specified port is invalid.
*
*/
CreateListeningPoint(port int, transport string) (ListeningPoint, error)
/**
* Deletes the specified ListeningPoint attached to this SipStack. The
* specified ListeningPoint is implicitly detached from this SipStack upon
* execution of this method, by removing the ListeningPoint from the
* ListeningPoints list of this SipStack.
*
* @param listeningPoint the SipProvider to be deleted from this SipStack.
* @throws ObjectInUseException if the specified ListeningPoint cannot be
* deleted because the ListeningPoint is currently in use.
*
*
*/
DeleteListeningPoint(listeningPoint ListeningPoint) (ObjectInUseException error)
/**
* Returns an Iterator of existing ListeningPoints created by this
* SipStack. All of the ListeningPoints of this SipStack belong to the
* same stack vendor.
*
* @return an Iterator containing all existing ListeningPoints created
* by this SipStack. Returns an empty Iterator if no ListeningPoints exist.
*/
GetListeningPoints() *list.List //Iterator
/**
* Gets the user friendly name that identifies this SipStack instance. This
* value is set using the Properties object passed to the
* {@link SipFactory#createSipStack(Properties)} method upon creation of
* the SipStack object.
*
* @return a string identifing the stack instance
*/
GetStackName() string
/**
* Gets the IP Address that identifies this SipStack instance. Every
* SipStack object must have an IP Address and only one SipStack object
* can service an IP Address. This value is set using the Properties
* object passed to the {@link SipFactory#createSipStack(Properties)} method upon
* creation of the SipStack object.
*
* @return a string identifing the IP Address
*
*/
GetIPAddress() string
/**
* Gets the Router object that identifies the default Router information
* of this SipStack, including the outbound proxy. This value is set using
* the Properties object passed to the
* {@link SipFactory#createSipStack(Properties)} method upon creation of
* the SipStack object.
*
* @return the Router object identifying the Router information.
*
*/
GetRouter() message.Router
/**
* This method returns the value of the retransmission filter helper
* function for User Agent applications. This value is set using the
* Properties object passed to the
* {@link SipFactory#createSipStack(Properties)} method upon creation of
* the SipStack object.
* <p>
* The default value of the retransmission filter boolean is <var>false</var>.
* When this value is set to <code>true</code>, retransmissions of ACK's and
* 2XX responses to an INVITE transaction are handled
* by the SipProvider, hence the application will not receive
* {@link Timeout#RETRANSMIT} notifications encapsulated in
* {@link javax.sip.TimeoutEvent}'s, however an application will be
* notified if the underlying transaction expires with a
* {@link Timeout#TRANSACTION} notification encapsulated in a TimeoutEvent.
*
* @return the value of the retransmission filter, <code>true</code> if the
* filter is set, <code>false</code> otherwise.
*
*/
IsRetransmissionFilterActive() bool
}
type Timeout ¶
type Timeout struct {
// contains filtered or unexported fields
}
func GetTimeout ¶
*
- This method returns the object value of the Timeout *
- @return The Timeout Object
- @param timeout The integer value of the Timeout
type TimeoutEvent ¶
type TimeoutEvent struct {
// contains filtered or unexported fields
}
*
- This class represents an Timeout event that is passed from a SipProvider to
- its SipListener. A specific message may need retransmitted on a specific
- transaction numerous times before it is acknowledged by the receiver. If the
- message is not acknowledged after a specified period in the underlying
- implementation the transaction will expire, this occurs usually
- after seven retransmissions. The mechanism to alert an application that a
- message for a an underlying transaction needs retransmitted (i.e. 200OK) or
- an underlying transaction has expired is a Timeout Event.
- <p>
- A Timeout Event can be of two different types, namely:
- <ul>
- <li>{@link Timeout#RETRANSMIT}
- <li>{@link Timeout#TRANSACTION}
- </ul>
- A TimeoutEvent contains the following information:
- <ul>
- <li>source - the SipProvider that sent the TimeoutEvent.
- <li>transaction - the transaction that this Timeout applies to.
- <li>isServerTransaction - boolean indicating whether the transaction refers to
- a client or server transaction.
- <li>timeout - indicates what type of {@link Timeout} occurred.
- </ul> *
- @see Timeout *
- @author Sun Microsystems *
func (*TimeoutEvent) GetClientTransaction ¶
func (this *TimeoutEvent) GetClientTransaction() ClientTransaction
*
- Gets the client transaction associated with this TimeoutEvent. *
- @return client transaction associated with this TimeoutEvent, or null if
- this event is specific to a server transaction.
func (*TimeoutEvent) GetServerTransaction ¶
func (this *TimeoutEvent) GetServerTransaction() ServerTransaction
*
- Gets the server transaction associated with this TimeoutEvent. *
- @return server transaction associated with this TimeoutEvent, or null if this
- event is specific to a client transaction.
func (*TimeoutEvent) GetTimeout ¶
func (this *TimeoutEvent) GetTimeout() Timeout
*
- Gets the event type of this TimeoutEvent. The event type can be used to
- determine if this Timeout Event is one of the following types:
- <ul>
- <li>{@link Timeout#TRANSACTION}
- <li>{@link Timeout#RETRANSMIT}
- </ul> *
- @return the event type of this TimeoutEvent
func (*TimeoutEvent) IsServerTransaction ¶
func (this *TimeoutEvent) IsServerTransaction() bool
*
- Indicates if the transaction associated with this TimeoutEvent is a server
- transaction. *
- @return returns true if a server transaction or false if a client
- transaction.
type Transaction ¶
type Transaction interface {
/**
* Gets the dialog object of this transaction object. A dialog only
* exists for a transaction when a session is setup between a User Agent
* Client and a User Agent Server, either by a 1xx Provisional Response
* for an early dialog or a 200OK Response for a committed dialog.
* <p>
* An implementation must always associate a dialog with a transaction
* which may result in the creation of a 'dummy' dialog so that the
* application may always query the dialog from the Transaction. However
* if a dialog is not yet initialized, the Dialog.getState() must return
* null to indicate that the dialog has been created but is not yet
* mapped by the stack to any specific state.
*
* @return the dialog object of this transaction object.
* @see Dialog
*/
GetDialog() Dialog
/**
* Returns the current state of the transaction. The allowable states for
* client and server transactions are defined in their respective objects.
*
* @return a TransactionState object determining the current state of the
* transaction.
*/
GetState() TransactionState
/**
* Returns the current value of the retransmit timer in milliseconds used
* to retransmit messages over unreliable transports for this transaction.
*
* @return the integer value of the retransmit timer in milliseconds.
* @throws UnsupportedOperationException if this method is not supported
* by the underlying implementation.
*/
GetRetransmitTimer() (retransmitTimer int, UnsupportedOperationException error)
/**
* Sets the value of the retransmit timer to the newly supplied timer value.
* The retransmit timer is expressed in milliseconds and its default value
* is 500ms. This method allows the application to change the transaction
* retransmit behavior for different networks. For example the gateway proxy,
* the internal intranet is likely to be relatively uncongested
* and the endpoints will be relatively close. The external network is the
* general Internet. This functionality allows different retransmit times
* for either side.
*
* @param retransmitTimer - the new integer value of the retransmit timer
* in milliseconds.
* @throws UnsupportedOperationException if this method is not supported
* by the underlying implementation.
*/
SetRetransmitTimer(retransmitTimer int) (UnsupportedOperationException error)
/**
* Returns a unique branch identifer that identifies this transaction. The
* branch identifier is used in the ViaHeader. The uniqueness property of
* the branch ID parameter to facilitate its use as a transaction ID, was
* not part of RFC 2543. The branch ID inserted by an element compliant
* with the RFC3261 specification MUST always begin with the characters
* "z9hG4bK". These 7 characters are used as a magic cookie, so that
* servers receiving the request can determine that the branch ID was
* constructed to be globally unique. The precise format of the branch
* token is implementation-defined. This method should always return the
* same branch identifier for the same transaction.
*
* @return the new branch that uniquely identifies this transaction.
*/
GetBranchId() string
/**
* Returns the request that created this transaction. The transaction state
* machine needs to keep the Request that resulted in the creation of this
* transaction while the transaction is still alive. Applications also need
* to access this information, e.g. a forking proxy server may wish to
* retrieve the original Invite request to cancel branches of a fork when
* a final Response has been received by one branch.
*
* @return the Request message that created this transaction.
*/
GetRequest() message.Request
}
type TransactionState ¶
type TransactionState struct {
// contains filtered or unexported fields
}
func GetTransactionState ¶
func GetTransactionState(transactionState int) (*TransactionState, error)
func (*TransactionState) GetValue ¶
func (this *TransactionState) GetValue() int
func (*TransactionState) ToString ¶
func (this *TransactionState) ToString() string
Source Files
¶
Directories
Click to show internal directories.
Click to hide internal directories.