Java Doc for Request.java in  » 6.0-JDK-Modules » Java-Advanced-Imaging » javax » sip » message » Java Source Code / Java DocumentationJava Source Code and Java Documentation

• 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.

• 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.

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 javax.sip.header.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.

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.

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.

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.

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

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.

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.