sip

package
Version: v0.0.0-...-892cec7 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 23, 2018 License: MIT Imports: 5 Imported by: 0

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

func GetTimeout(timeout int) (*Timeout, error)

*

* This method returns the object value of the Timeout
*
* @return  The Timeout Object
* @param timeout The integer value of the Timeout

func (*Timeout) GetValue

func (this *Timeout) GetValue() int

*

* This method returns the integer value of the Timeout
*
* @return The integer value of the Timeout

func (*Timeout) ToString

func (this *Timeout) ToString() string

*

* This method returns a string version of this class.
*
* @return The string version 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

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL