request.html

jsip开发文档,对于开发SIP软电话和presence服务很有用

 other means have been used.
 <p>
 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.
 <p>
 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.
 <p>
 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 
 <p>
 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. 
 <p>
 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.
<P>
<DL>
<DT><B>See Also:</B><DD><A HREF="../../../constant-values.html#javax.sip.message.Request.NOTIFY">Constant Field Values</A></DL>
</DL>
<HR>

<A NAME="SUBSCRIBE"><!-- --></A><H3>
SUBSCRIBE</H3>
<PRE>
static final java.lang.String <B>SUBSCRIBE</B></PRE>
<DL>
<DD>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. 
 <p>
 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.
 <p>
 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. 
 <p>
 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.
 <p>
 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.
 <p>
 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.
<P>
<DL>
<DT><B>See Also:</B><DD><A HREF="../../../constant-values.html#javax.sip.message.Request.SUBSCRIBE">Constant Field Values</A></DL>
</DL>
<HR>

<A NAME="MESSAGE"><!-- --></A><H3>
MESSAGE</H3>
<PRE>
static final java.lang.String <B>MESSAGE</B></PRE>
<DL>
<DD>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.
 <p>
 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. 
 <p>
 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.
 <p>
 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. 
 <p>
 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.
<P>
<DL>
<DT><B>See Also:</B><DD><A HREF="../../../constant-values.html#javax.sip.message.Request.MESSAGE">Constant Field Values</A></DL>
</DL>
<HR>

<A NAME="REFER"><!-- --></A><H3>
REFER</H3>
<PRE>
static final java.lang.String <B>REFER</B></PRE>
<DL>
<DD>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.
 <p>
 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.
 <p>
 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.
<P>
<DL>
<DT><B>See Also:</B><DD><A HREF="../../../constant-values.html#javax.sip.message.Request.REFER">Constant Field Values</A></DL>
</DL>
<HR>

<A NAME="INFO"><!-- --></A><H3>
INFO</H3>
<PRE>
static final java.lang.String <B>INFO</B></PRE>
<DL>
<DD>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.
 <p>
 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 <A HREF="../../../javax/sip/header/ExtensionHeader.html" title="interface in javax.sip.header"><CODE>ExtensionHeader</CODE></A> 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.
<P>
<DL>
<DT><B>See Also:</B><DD><A HREF="../../../constant-values.html#javax.sip.message.Request.INFO">Constant Field Values</A></DL>
</DL>
<HR>

<A NAME="PRACK"><!-- --></A><H3>
PRACK</H3>
<PRE>
static final java.lang.String <B>PRACK</B></PRE>
<DL>
<DD>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. 
 <p>
 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,