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 ¶
Click to show internal directories.
Click to hide internal directories.