dialog.html

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

 sequence of dialog requests) outside of the Dialog using the
 <A HREF="../../javax/sip/ClientTransaction.html#sendRequest()"><CODE>ClientTransaction.sendRequest()</CODE></A> method. When sending a request
 using the Transaction the Dialog state is unaffected.
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
</DL>
</DD>
</DL>
<HR>

<A NAME="createRequest(java.lang.String)"><!-- --></A><H3>
createRequest</H3>
<PRE>
<A HREF="../../javax/sip/message/Request.html" title="interface in javax.sip.message">Request</A> <B>createRequest</B>(java.lang.String&nbsp;method)
                      throws <A HREF="../../javax/sip/SipException.html" title="class in javax.sip">SipException</A></PRE>
<DL>
<DD>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
 <A HREF="../../javax/sip/Dialog.html#sendRequest(javax.sip.ClientTransaction)"><CODE>sendRequest(ClientTransaction)</CODE></A> method. Therefore any
 Request created by this method must be sent via the
 <A HREF="../../javax/sip/Dialog.html#sendRequest(javax.sip.ClientTransaction)"><CODE>sendRequest(ClientTransaction)</CODE></A> method and not via its
 <A HREF="../../javax/sip/ClientTransaction.html#sendRequest()"><CODE>ClientTransaction.sendRequest()</CODE></A> 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. This method may not be used for creating
 PRACK or ACK. Implementations should throw SipException if this method is
 called for creating ACK or PRACK.
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>method</CODE> - the string value that determines if the request to be created.
<DT><B>Returns:</B><DD>the newly created Request message on this Dialog.
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../javax/sip/SipException.html" title="class in javax.sip">SipException</A></CODE> - if the Dialog is not yet established (i.e. dialog state
             equals null) or is terminated or if the method is invoked for
             ACK or PRACK.</DL>
</DD>
</DL>
<HR>

<A NAME="createReliableProvisionalResponse(int)"><!-- --></A><H3>
createReliableProvisionalResponse</H3>
<PRE>
<A HREF="../../javax/sip/message/Response.html" title="interface in javax.sip.message">Response</A> <B>createReliableProvisionalResponse</B>(int&nbsp;statusCode)
                                           throws <A HREF="../../javax/sip/InvalidArgumentException.html" title="class in javax.sip">InvalidArgumentException</A>,
                                                  <A HREF="../../javax/sip/SipException.html" title="class in javax.sip">SipException</A></PRE>
<DL>
<DD>Creates a new reliable provisional response based on an Invite request
 that created this Dialog or that is now refreshing this Dialog. This new
 Response does not contain a body. Only the required headers are copied
 from the Request. The response will include also the following headers:
 <ul>
 <li> RequireHeader
 <li> RSeqHeader
 </ul>
 The RequireHeader will include the 100rel option tag. The Dialog will
 handle the RSeq count that will be updated and icreased if needed when
 the reliable provisional response is sent. Any Response created by this
 method must be sent via the
 <A HREF="../../javax/sip/Dialog.html#sendReliableProvisionalResponse(javax.sip.message.Response)"><CODE>sendReliableProvisionalResponse( Response)</CODE></A> method.
 <p>
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>statusCode</CODE> - the new integer of the statusCode value of this Message.
<DT><B>Returns:</B><DD>the newly created Response object.
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../javax/sip/InvalidArgumentException.html" title="class in javax.sip">InvalidArgumentException</A></CODE> - when an invalid status code or request method is supplied.
<DD><CODE><A HREF="../../javax/sip/SipException.html" title="class in javax.sip">SipException</A></CODE> - when the Dialog is not a server dialog or if this
         method is called after a final response is sent to the
         ServerTransactin that created the Dialog.<DT><B>Since:</B></DT>
  <DD>1.2</DD>
</DL>
</DD>
</DL>
<HR>

<A NAME="sendRequest(javax.sip.ClientTransaction)"><!-- --></A><H3>
sendRequest</H3>
<PRE>
void <B>sendRequest</B>(<A HREF="../../javax/sip/ClientTransaction.html" title="interface in javax.sip">ClientTransaction</A>&nbsp;clientTransaction)
                 throws <A HREF="../../javax/sip/TransactionDoesNotExistException.html" title="class in javax.sip">TransactionDoesNotExistException</A>,
                        <A HREF="../../javax/sip/SipException.html" title="class in javax.sip">SipException</A></PRE>
<DL>
<DD>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
 <A HREF="../../javax/sip/SipProvider.html#getNewClientTransaction(javax.sip.message.Request)"><CODE>SipProvider.getNewClientTransaction(Request)</CODE></A>. 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 method 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>
 A Dialog may be created by an INVITE request and subsequently
 SUBSCRIBE/NOTIFY are sent withing that Dialog. In this case the
 application may call <A HREF="../../javax/sip/Dialog.html#terminateOnBye(boolean)"><CODE>terminateOnBye(boolean)</CODE></A> to prevent the Dialog
 from Terminating upon reciept of a BYE.
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>clientTransaction</CODE> - -
            the new ClientTransaction object identifying this transaction,
            this clientTransaction should be requested from
            <A HREF="../../javax/sip/SipProvider.html#getNewClientTransaction(javax.sip.message.Request)"><CODE>SipProvider.getNewClientTransaction(Request)</CODE></A>
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../javax/sip/TransactionDoesNotExistException.html" title="class in javax.sip">TransactionDoesNotExistException</A></CODE> - if the clientTransaction does not correspond to any existing
             client transaction.
<DD><CODE><A HREF="../../javax/sip/SipException.html" title="class in javax.sip">SipException</A></CODE> - if implementation cannot send the Request for any reason.</DL>
</DD>
</DL>
<HR>

<A NAME="sendReliableProvisionalResponse(javax.sip.message.Response)"><!-- --></A><H3>
sendReliableProvisionalResponse</H3>
<PRE>
void <B>sendReliableProvisionalResponse</B>(<A HREF="../../javax/sip/message/Response.html" title="interface in javax.sip.message">Response</A>&nbsp;relResponse)
                                     throws <A HREF="../../javax/sip/SipException.html" title="class in javax.sip">SipException</A></PRE>
<DL>
<DD>Sends a reliable provisional response to the remote party of this dialog.
 When an application wishes to send a reliable provisional response on the
 Invite transaction that created this dialog or that is now refreshing
 this dialog, it creates a reliable provisional response message with
 <A HREF="../../javax/sip/Dialog.html#createReliableProvisionalResponse(int)"><CODE>createReliableProvisionalResponse(int)</CODE></A>. This Response is
 passed to this method that sends it. This method will update the RSeq
 header of the response if needed and will increase the RSeq count of the
 Transaction. The application will not be able to send further reliable
 provisional responses for this Dialog until PRACK is received for a
 previously sent provisional response. The only response that can be sent
 in parallel with an active reliable Provisional Response is a final
 response. The Final response will stop retransmission of the reliable
 responses.
 <p>
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>relResponse</CODE> - -
            the reliable provisional response
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../javax/sip/SipException.html" title="class in javax.sip">SipException</A></CODE> - if implementation cannot send the Request for any reason
             (e.g. because another reliable response is still pending).<DT><B>Since:</B></DT>
  <DD>1.2</DD>
</DL>
</DD>
</DL>
<HR>

<A NAME="createPrack(javax.sip.message.Response)"><!-- --></A><H3>
createPrack</H3>
<PRE>
<A HREF="../../javax/sip/message/Request.html" title="interface in javax.sip.message">Request</A> <B>createPrack</B>(<A HREF="../../javax/sip/message/Response.html" title="interface in javax.sip.message">Response</A>&nbsp;relResponse)
                    throws <A HREF="../../javax/sip/DialogDoesNotExistException.html" title="class in javax.sip">DialogDoesNotExistException</A>,
                           <A HREF="../../javax/sip/SipException.html" title="class in javax.sip">SipException</A></PRE>
<DL>
<DD>Creates a new PRACK Request message based on a reliable provisional
 response received by this Dialog and the Dialog internal information. 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
 <li> RAckHeader
 </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
 <A HREF="../../javax/sip/Dialog.html#sendRequest(javax.sip.ClientTransaction)"><CODE>sendRequest(ClientTransaction)</CODE></A> method. Therefore any
 Request created by this method must be sent via the
 <A HREF="../../javax/sip/Dialog.html#sendRequest(javax.sip.ClientTransaction)"><CODE>sendRequest(ClientTransaction)</CODE></A> method and not via its
 <A HREF="../../javax/sip/ClientTransaction.html#sendRequest()"><CODE>ClientTransaction.sendRequest()</CODE></A> 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.
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>relResponse</CODE> - the reliable provisional response that should result in a
            prack reques.
<DT><B>Returns:</B><DD>the newly created Request message on this Dialog.
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../javax/sip/SipException.html" title="class in javax.sip">SipException</A></CODE> - if the Method of the transaction that created the Dialog or
             Refeshing the Dialog is not an INVITE ( for example
             SUBSCRIBE).
<DD><CODE><A HREF="../../javax/sip/DialogDoesNotExistException.html" title="class in javax.sip">DialogDoesNotExistException</A></CODE> - if the Dialog is not yet established (i.e. dialog state
             equals null) or is terminated.<DT><B>Since:</B></DT>
  <DD>1.2</DD>
</DL>
</DD>
</DL>
<HR>

<A NAME="createAck(long)"><!-- --></A><H3>
createAck</H3>
<PRE>
<A HREF="../../javax/sip/message/Request.html" title="interface in javax.sip.message">Request</A> <B>createAck</B>(long&nbsp;cseq)
                  throws <A HREF="../../javax/sip/InvalidArgumentException.html" title="class in javax.sip">InvalidArgumentException</A>,
                         <A HREF="../../javax/sip/SipException.html" title="class in javax.sip">SipException</A></PRE>
<DL>
<DD>Creates an ACK request for an Invite that was responded with 2xx
 response. The cseq number for the invite is supplied to relate the ACK to
 its original invite request.
<P>
<DD><DL>
</DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>cseq</CODE> - -
            the CSeq number to be placed in the ACK request.
<DT><B>Returns:</B><DD>The newly created ACK request message.
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../javax/sip/InvalidArgumentException.html" title="class in javax.sip">InvalidArgumentException</A></CODE> - if there is a problem with the supplied cseq ( for example <=
             0 ).
<DD><CODE><A HREF="../../javax/sip/SipException.html" title="class in javax.sip">SipException</A></CODE> - if the cseq does not relate to a previously sent INVITE or if
             the Method that created the Dialog is not an INVITE ( for
             example SUBSCRIBE)<DT><B>Since:</B></DT>
  <DD>1.2</DD>
</DL>
</DD>
</DL>
<HR>

<A NAME="sendAck(javax.sip.message.Request)"><!-- --></A><H3>
sendAck</H3>
<PRE>
void <B>sendAck</B>(<A HREF="../../javax/sip/message/Request.html" title="interface in javax.sip.message">Request</A>&nbsp;ackRequest)
             throws <A HREF="../../javax/sip/SipException.html" title="class in javax.sip">SipException</A></PRE>