javax.sip.message

Interface Request

All Superinterfaces:

Cloneable, Message, Serializable

All Known Subinterfaces:

RequestExt

All Known Implementing Classes:

SIPRequest

public interface Request
extends Message

A SIP Request is a request from a client to a server. The following Requests method names are defined by RFC3261:

• ACK - confirms that client has received a final Response to an INVITE Request.
• BYE - indicates to the server that client wishes to release the call leg.
• CANCEL - cancels a pending User Agent Client Request.
• INVITE - indicates that user or service is being invited to participate in a session.
• OPTIONS - queries a server with regards to its capabilities.
• REGISTER - registers contact information with a SIP server.

This specifications also supports the following method name extensions, documented in the following standards track RFCs:

• INFO - used to carry session related control information that is generated during a session. This functionality is defined in RFC2976.
• PRACK - similiar in operation to ACK, however specific to the reliability of provisional Responses. This functionality is defined in RFC3262.
• UPDATE - allows a client to update parameters of a session without impacting the state of a dialog. This functionality is defined in RFC3311.
• SUBSCRIBE - provides an extensible framework by which SIP nodes can request notification from remote nodes indicating that certain events have occurred. This functionality is defined in RFC3265.
• NOTIFY - provides an extensible framework by which SIP nodes can get notification from remote nodes indicating that certain events have occurred. This functionality is defined in RFC3265.
• MESSAGE - for sending instant messages using a metaphor similar to that of a two-way pager or SMS enabled handset. This functionality is defined in RFC3428.
• REFER - requests that the recipient REFER to a resource provided in the request. This functionality is defined in RFC3515.
• PUBLISH - for publishing event state. This functionality is defined in RFC3903.

A valid SIP request formulated by a User Agent Client MUST, at a minimum, contain the following header fields: To, From, CSeq, Call-ID, Max-Forwards, and Via; all of these header fields are mandatory in all SIP requests. These six header fields are the fundamental building blocks of a SIP message, as they jointly provide for most of the critical message routing services including the addressing of messages, the routing of responses, limiting message propagation, ordering of messages, and the unique identification of transactions. These header fields are in addition to the mandatory request line, which contains the method, Request-URI, and SIP version.

Version:

1.2

Author:

BEA Systems, NIST

Field Summary

Fields

Modifier and Type	Field and Description
static String	ACK An ACK is used to acknowledge the successful receipt of a message in a transaction.
static String	BYE The BYE request is used to terminate a specific session or attempted session.
static String	CANCEL The CANCEL request is used to cancel a previous request sent by a client.
static String	INFO INFO is an extension method which allows for the carrying of session related control information that is generated during a session.
static String	INVITE The INVITE method is used by an user agent client that desires to initiate a session, session examples include, audio, video, or a game.
static String	MESSAGE Message is an extension method that allows the transfer of Instant Messages.
static String	NOTIFY Notify is an extension method that informs subscribers of changes in state to which the subscriber has a subscription.
static String	OPTIONS The OPTIONS method allows a User Agent to query another User Agent or a proxy server as to its capabilities.
static String	PRACK PRACK is an extension method that plays the same role as ACK, but for provisional responses.
static String	PUBLISH PUBLISH is an extension method that allows a client to publish event state (such as presence information).
static String	REFER Refer is an extension method that requests that the recipient REFER to a resource provided in the request, this can be used to enable many applications such as Call Transfer.
static String	REGISTER The REGISTER method requests the addition, removal, and query of bindings.
static String	SUBSCRIBE Subscribe is an extension method that is used to request current state and state updates from a remote node.
static String	UPDATE UPDATE is an extension method that allows a client to update parameters of a session (such as the set of media streams and their codecs) but has no impact on the state of a dialog.

Method Summary

Methods

Modifier and Type	Method and Description
String	getMethod() Gets method string of this Request message.
URI	getRequestURI() Gets the URI Object identifying the request URI of this Request, which indicates the user or service to which this request is addressed.
void	setMethod(String method) Sets the method of Request to the newly supplied value.
void	setRequestURI(URI requestURI) Sets the RequestURI of Request.

Methods inherited from interface javax.sip.message.Message

addFirst, addHeader, addLast, clone, equals, getContent, getContentDisposition, getContentEncoding, getContentLanguage, getContentLength, getExpires, getHeader, getHeaderNames, getHeaders, getRawContent, getSIPVersion, getUnrecognizedHeaders, hashCode, removeContent, removeFirst, removeHeader, removeLast, setContent, setContentDisposition, setContentEncoding, setContentLanguage, setContentLength, setExpires, setHeader, setSIPVersion, toString

Field Detail

ACK

static final String ACK

An ACK is used to acknowledge the successful receipt of a message in a transaction. It is also used to illustrate the successful setup of a dialog via the a three-way handshake between an UAC and an UAS for an Invite transaction.

See Also:

Constant Field Values

BYE

static final String BYE

The BYE request is used to terminate a specific session or attempted session. When a BYE is received on a dialog, any session associated with that dialog SHOULD terminate. A User Agent MUST NOT send a BYE outside of a dialog. The caller's User Agent MAY send a BYE for either confirmed or early dialogs, and the callee's User Agent MAY send a BYE on confirmed dialogs, but MUST NOT send a BYE on early dialogs. However, the callee's User Agent MUST NOT send a BYE on a confirmed dialog until it has received an ACK for its 2xx response or until the server transaction times out. If no SIP extensions have defined other application layer states associated with the dialog, the BYE also terminates the dialog.

See Also:

Constant Field Values

CANCEL

static final String CANCEL

The CANCEL request is used to cancel a previous request sent by a client. Specifically, it asks the UAS to cease processing the request and to generate an error response to that request. CANCEL has no effect on a request to which a UAS has already given a final response. Because of this, it is most useful to CANCEL requests to which it can take a server long time to respond. For this reason, CANCEL is best for INVITE requests, which can take a long time to generate a response.

See Also:

Constant Field Values

INVITE

static final String INVITE

The INVITE method is used by an user agent client that desires to initiate a session, session examples include, audio, video, or a game. The INVITE request asks a server to establish a session. This request may be forwarded by proxies, eventually arriving at one or more UAS's that can potentially accept the invitation. These UAS's will frequently need to query the user about whether to accept the invitation. After some time, those UAS's can accept the invitation (meaning the session is to be established) by sending a 2xx response. If the invitation is not accepted, a 3xx, 4xx, 5xx or 6xx response is sent, depending on the reason for the rejection. Before sending a final response, the UAS can also send provisional responses (1xx) to advise the UAC of progress in contacting the called user.

See Also:

Constant Field Values

OPTIONS

static final String OPTIONS

The OPTIONS method allows a User Agent to query another User Agent or a proxy server as to its capabilities. This allows a client to discover information about the supported methods, content types, extensions, codecs, etc. without "ringing" the other party. For example, before a client inserts a Require header field into an INVITE listing an option that it is not certain the destination UAS supports, the client can query the destination UAS with an OPTIONS to see if this option is returned in a Supported header field. All User Agents MUST support the OPTIONS method.

See Also:

Constant Field Values

REGISTER

static final String REGISTER

The REGISTER method requests the addition, removal, and query of bindings. A REGISTER request can add a new binding between an address-of-record and one or more contact addresses. Registration on behalf of a particular address-of-record can be performed by a suitably authorized third party. A client can also remove previous bindings or query to determine which bindings are currently in place for an address-of-record. A REGISTER request does not establish a dialog. Registration entails sending a REGISTER request to a special type of UAS known as a registrar. A registrar acts as the front end to the location service for a domain, reading and writing mappings based on the contents of REGISTER requests. This location service is then typically consulted by a proxy server that is responsible for routing requests for that domain.

See Also:

Constant Field Values

NOTIFY

static final String NOTIFY

Notify is an extension method that informs subscribers of changes in state to which the subscriber has a subscription. Subscriptions are typically put in place using the SUBSCRIBE method; however, it is possible that other means have been used.

When a SUBSCRIBE request is answered with a 200-class response, the notifier MUST immediately construct and send a NOTIFY request to the subscriber. When a change in the subscribed state occurs, the notifier SHOULD immediately construct and send a NOTIFY request, subject to authorization, local policy, and throttling considerations.

A NOTIFY does not terminate its corresponding subscription. i.e. a single SUBSCRIBE request may trigger several NOTIFY requests. NOTIFY requests MUST contain a "Subscription-State" header with a value of "active", "pending", or "terminated". As in SUBSCRIBE requests, NOTIFY "Event" headers will contain a single event package name for which a notification is being generated. The package name in the "Event" header MUST match the "Event" header in the corresponding SUBSCRIBE message. If an "id" parameter was present in the SUBSCRIBE message, that "id" parameter MUST also be present in the corresponding NOTIFY messages.

Event packages may define semantics associated with the body of their NOTIFY requests; if they do so, those semantics apply. NOTIFY bodies are expected to provide additional details about the nature of the event which has occurred and the resultant resource state. When present, the body of the NOTIFY request MUST be formatted into one of the body formats specified in the "Accept" header of the corresponding SUBSCRIBE request. This body will contain either the state of the subscribed resource or a pointer to such state in the form of a URI

A NOTIFY request is considered failed if the response times out, or a non-200 class response code is received which has no "Retry-After" header and no implied further action which can be taken to retry the request. If a NOTIFY request receives a 481 response, the notifier MUST remove the corresponding subscription even if such subscription was installed by non-SUBSCRIBE means.

If necessary, clients may probe for the support of NOTIFY using the OPTIONS. The presence of the "Allow-Events" header in a message is sufficient to indicate support for NOTIFY. The "methods" parameter for Contact may also be used to specifically announce support for NOTIFY messages when registering.

See Also:

Constant Field Values

SUBSCRIBE

static final String SUBSCRIBE

Subscribe is an extension method that is used to request current state and state updates from a remote node. SUBSCRIBE requests SHOULD contain an "Expires" header, which indicates the duration of the subscription. In order to keep subscriptions effective beyond the duration communicated in the "Expires" header, subscribers need to refresh subscriptions on a periodic basis using a new SUBSCRIBE message on the same dialog. If no "Expires" header is present in a SUBSCRIBE request, the implied default is defined by the event package being used.

200-class responses to a SUBSCRIBE request indicate that the subscription has been accepted, and that a NOTIFY will be sent immediately. If the subscription resource has no meaningful state at the time that the SUBSCRIBE message is processed, this NOTIFY message MAY contain an empty or neutral body. 200-class responses to SUBSCRIBE requests also MUST contain an "Expires" header. The period of time in the response MAY be shorter but MUST NOT be longer than specified in the request. The period of time in the response is the one which defines the duration of the subscription. An "expires" parameter on the "Contact" header has no semantics for SUBSCRIBE and is explicitly not equivalent to an "Expires" header in a SUBSCRIBE request or response.

The Request URI of a SUBSCRIBE request, contains enough information to route the request to the appropriate entity. It also contains enough information to identify the resource for which event notification is desired, but not necessarily enough information to uniquely identify the nature of the event. Therefore Subscribers MUST include exactly one "Event" header in SUBSCRIBE requests, indicating to which event or class of events they are subscribing. The "Event" header will contain a token which indicates the type of state for which a subscription is being requested.

As SUBSCRIBE requests create a dialog, they MAY contain an "Accept" header. This header, if present, indicates the body formats allowed in subsequent NOTIFY requests. Event packages MUST define the behavior for SUBSCRIBE requests without "Accept" headers. If an initial SUBSCRIBE is sent on a pre-existing dialog, a matching 200-class response or successful NOTIFY request merely creates a new subscription associated with that dialog. Multiple subscriptions can be associated with a single dialog.

Unsubscribing is handled in the same way as refreshing of a subscription, with the "Expires" header set to "0". Note that a successful unsubscription will also trigger a final NOTIFY message.

If necessary, clients may probe for the support of SUBSCRIBE using the OPTIONS. The presence of the "Allow-Events" header in a message is sufficient to indicate support for SUBSCRIBE. The "methods" parameter for Contact may also be used to specifically announce support for SUBSCRIBE messages when registering.

See Also:

Constant Field Values

MESSAGE

static final String MESSAGE

Message is an extension method that allows the transfer of Instant Messages. The MESSAGE request inherits all the request routing and security features of SIP. MESSAGE requests carry the content in the form of MIME body parts. The actual communication between participants happens in the media sessions, not in the SIP requests themselves. The MESSAGE method changes this assumption.

MESSAGE requests do not themselves initiate a SIP dialog; under normal usage each Instant Message stands alone, much like pager messages, that is there are no explicit association between messages. MESSAGE requests may be sent in the context of a dialog initiated by some other SIP request. If a MESSAGE request is sent within a dialog, it is "associated" with any media session or sessions associated with that dialog.

When a user wishes to send an instant message to another, the sender formulates and issues a Message request. The Request-URI of this request will normally be the "address of record" for the recipient of the instant message, but it may be a device address in situations where the client has current information about the recipient's location. The body of the request will contain the message to be delivered.

Provisional and final responses to the request will be returned to the sender as with any other SIP request. Normally, a 200 OK response will be generated by the user agent of the request's final recipient. Note that this indicates that the user agent accepted the message, not that the user has seen it.

The UAC MAY add an Expires header field to limit the validity of the message content. If the UAC adds an Expires header field with a non-zero value, it SHOULD also add a Date header field containing the time the message is sent. Most SIP requests are used to setup and modify communication sessions.

See Also:

Constant Field Values

REFER

static final String REFER

Refer is an extension method that requests that the recipient REFER to a resource provided in the request, this can be used to enable many applications such as Call Transfer. The REFER method indicates that the recipient (identified by the Request-URI) should contact a third party using the contact information provided in the request. A REFER request MUST contain exactly one Refer-To header field value and MAY contain a body. A receiving agent may choose to process the body according to its Content-Type.

A User Agent accepting a well-formed REFER request SHOULD request approval from the user to proceed. If approval is granted, the User Agent MUST contact the resource identified by the URI. SIP proxies do not require modification to support the REFER method. A proxy should process a REFER request the same way it processes an OPTIONS request.

A REFER request implicitly establishes a subscription to the "refer" event. The agent issuing the REFER can terminate this subscription prematurely by unsubscribing. A REFER request MAY be placed outside the scope of a dialog created with an INVITE. REFER creates a dialog, and MAY be Record-Routed, hence MUST contain a single Contact header field value. REFERs occurring inside an existing dialog MUST follow the Route/Record-Route logic of that dialog. The NOTIFY mechanism MUST be used to inform the agent sending the REFER of the status of the reference. The dialog identifiers of each NOTIFY must match those of the REFER as they would if the REFER had been a SUBSCRIBE request. If more than one REFER is issued in the same dialog, the dialog identifiers do not provide enough information to associate the resulting NOTIFYs with the proper REFER. Therefore it MUST include an "id" parameter in the Event header field of each NOTIFY containing the sequence number of the REFER this NOTIFY is associated with. A REFER sent within the scope of an existing dialog will not fork. A REFER sent outside the context of a dialog MAY fork, and if it is accepted by multiple agents, MAY create multiple subscriptions.

See Also:

Constant Field Values

INFO

static final String INFO

INFO is an extension method which allows for the carrying of session related control information that is generated during a session. One example of such session control information is ISUP and ISDN signaling messages used to control telephony call services. The purpose of the INFO message is to carry application level information along the SIP signaling path. The signaling path for the INFO method is the signaling path established as a result of the call setup. This can be either direct signaling between the calling and called user agents or a signaling path involving SIP proxy servers that were involved in the call setup and added themselves to the Record-Route header on the initial INVITE message.

The INFO method is used for communicating mid-session signaling information, it is not used to change the state of SIP calls, nor does it change the state of sessions initiated by SIP. Rather, it provides additional optional information which can further enhance the application using SIP. The mid-session information can be communicated in either an INFO message header or as part of a message body. There are no specific semantics associated with INFO. The semantics are derived from the body or new headers defined for usage in INFO. JAIN SIP provides the facility to send ExtensionHeader in messages. The INFO request MAY contain a message body. Bodies which imply a change in the SIP call state or the sessions initiated by SIP MUST NOT be sent in an INFO message.

See Also:

Constant Field Values

PRACK

static final String PRACK

PRACK is an extension method that plays the same role as ACK, but for provisional responses. PRACK is a normal SIP message, like BYE. As such, its own reliability is ensured hop-by-hop through each stateful proxy. Also like BYE, but unlike ACK, PRACK has its own response. In order to achieve reliability of provisional responses, in a similiar manner to 2xx final responses to INVITE, reliable provisional responses are retransmitted with an exponential backoff, which cease when a PRACK message is received. The PRACK messages contain an RAck header field, which indicates the sequence number of the provisional response that is being acknowledged.

PRACK is like any other request within a dialog, and is treated likewise. In particular, a UAC SHOULD NOT retransmit the PRACK request when it receives a retransmission of the provisional response being acknowledged, although doing so does not create a protocol error. A matching PRACK is defined as one within the same dialog as the response, and whose method, CSeq-num, and RSeq-num in the RAck header field match, respectively, the method and sequence number from the CSeq and the sequence number from the RSeq header of the reliable provisional response. PRACK requests MAY contain bodies, which are interpreted according to their type and disposition.

See Also:

Constant Field Values

UPDATE

static final String UPDATE

UPDATE is an extension method that allows a client to update parameters of a session (such as the set of media streams and their codecs) but has no impact on the state of a dialog. In that sense, it is like a re-INVITE, but unlike re-INVITE, it can be sent before the initial INVITE has been completed. This makes it very useful for updating session parameters within early dialogs. Operation of this extension is straightforward, the caller begins with an INVITE transaction, which proceeds normally. Once a dialog is established, the caller can generate an UPDATE method that contains an SDP offer for the purposes of updating the session. The response to the UPDATE method contains the answer. The Allow header field is used to indicate support for the UPDATE method. There are additional constraints on when UPDATE can be used, based on the restrictions of the offer/answer model. Although UPDATE can be used on confirmed dialogs, it is RECOMMENDED that a re-INVITE be used instead. This is because an UPDATE needs to be answered immediately, ruling out the possibility of user approval. Such approval will frequently be needed, and is possible with a re-INVITE.

See Also:

Constant Field Values

PUBLISH

static final String PUBLISH

PUBLISH is an extension method that allows a client to publish event state (such as presence information). It is sent outside of any dialog, and is not dialog creating. PUBLISH is similar to REGISTER in that it allows a user to create, modify, and remove state in another entity which manages this state on behalf of the user. Addressing a PUBLISH request is identical to addressing a SUBSCRIBE request. The Request-URI of a PUBLISH request is populated with the address of the resource for which the user wishes to publish event state. The user may in turn have multiple User Agents or endpoints that publish event state. Each endpoint may publish its own unique state, out of which the event state compositor generates the composite event state of the resource. In addition to a particular resource, all published event state is associated with a specific event package. Through a subscription to that event package, the user is able to discover the composite event state of all of the active publications.

PUBLISH requests create soft state in the event state compositor. This event soft state has a defined lifetime and will expire after a negotiated amount of time, requiring the publication to be refreshed by subsequent PUBLISH requests. There may also be event hard state provisioned for each resource for a particular event package. This event state represents the resource state that is present at all times, and does not expire.The event state compositor may use event hard state in the absence of, or in addition to, event soft state provided through the PUBLISH mechanism.

Clients may probe for the support of PUBLISH using theOPTIONS request. The presence of "PUBLISH" in the "Allow" header field in a response to an OPTIONS request indicates support for the PUBLISH method. In addition, the "Allow-Events" header field indicates the supported event packages.

A PUBLISH request does not establish a dialog. A UAC MAY include a Route header field in a PUBLISH request based on a pre-existing route set. The Record-Route header field has no meaning in PUBLISH requests or responses, and MUST be ignored if present. In particular, the UAC MUST NOT create a new route set based on the presence or absence of a Record-Route header field in any response to a PUBLISH request. The PUBLISH request MAY contain a Contact header field, but including one in a PUBLISH request has no meaning in the event publication context and will be ignored. A PUBLISH request may be sent within an existing dialog. In that case, the request is received in the context of any media session or sessions associated with that dialog. A new PUBLISH should not be sent (not a re-transmission) for the same Request-URI, until they have received a final response for the previous one or the previous PUBLISH request has timed out.

Since:

v1.2

See Also:

Constant Field Values

Method Detail

getMethod

String getMethod()

Gets method string of this Request message.

Returns:

the method of this Request message.

setMethod

void setMethod(String method)
               throws ParseException

Sets the method of Request to the newly supplied value. The standard RFC3261 methods are REGISTER for registering contact information, INVITE, ACK, and CANCEL for setting up sessions, BYE for terminating sessions, and OPTIONS for querying servers about their capabilities.

Parameters:

method - - the new string value of the method of Request

Throws:

ParseException - which signals that an error has been reached unexpectedly while parsing the method value.

getRequestURI

URI getRequestURI()

Gets the URI Object identifying the request URI of this Request, which indicates the user or service to which this request is addressed.

Returns:

Request URI of Request

setRequestURI

void setRequestURI(URI requestURI)

Sets the RequestURI of Request. The Request-URI is a SIP or SIPS URI or a general URI. It indicates the user or service to which this request is being addressed. SIP elements MAY support Request-URIs with schemes other than "sip" and "sips", for example the "tel" URI scheme. SIP elements MAY translate non-SIP URIs using any mechanism at their disposal, resulting in SIP URI, SIPS URI, or some other scheme.

Parameters:

requestURI - - the new Request URI of this request message