rfc3050.txt

最新的RFC

Lennox, et al.               Informational                     [Page 23]

RFC 3050                      CGI for SIP                   January 2001


   A SIP CGI script's output consists of any number of messages, each
   corresponding to actions which the script is requesting that the
   server perform.  Messages consist of an action line, whose syntax is
   specific to the type of action, followed by CGI header fields and SIP
   header fields.  Action lines determine the nature of the action
   performed, and are described in section 5.6.1.  CGI header fields
   pass additional instructions or information to the server, and are
   described in section 5.6.2.

   A message MUST contain exactly one action line, MAY also contain any
   number of CGI header fields and SIP header fields, and MAY contain a
   SIP body.

   All header fields (both SIP and CGI) occurring in an output message
   MUST be specified one per line; SIP CGI 1.1 makes no provision for
   continuation lines.

   The generic syntax of CGI header fields is specified in section
   5.6.2.

   A server MAY choose to honor only some of the requests or responses;
   in particular, it SHOULD NOT accept any responses following a Status
   message which sends a definitive non-success response.

   The messages sent by a script are delimited as follows:

        1.   A message begins with an action line.

        2.   If the message does not contain a Content-Type header
             field, or if it contains the header field "Content-Length:
             0", then it is terminated by a blank line.

        3.   If the message contains both Content-Type and Content-
             Length header fields, the message has a body consisting of
             the Content-Length octets following the blank line below
             the set.  The next message begins after the body (and
             optionally some number of blank lines).  If the script
             closes its output prematurely, the server SHOULD report a
             500-class server error.

        4.   If the message contains Content-Type but not Content-
             Length, the message's body similarly begins with the blank
             line following the set; this body extends until the script
             closes its output.  In this case, this is necessarily the
             last message the script can send.  The server SHOULD insert
             a Content-Length header containing the amount of data read
             before the script closed its output.




Lennox, et al.               Informational                     [Page 24]

RFC 3050                      CGI for SIP                   January 2001


        5.   If a message contains a non-zero Content-Length but does
             not contain a Content-Type, it is an error.  The server
             SHOULD report a 500-class server error.

        The output of a SIP CGI script is intended to be
        syntactically identical to that of a UDP packet in which
        multiple requests or responses are sent, so that the same
        message parser may be used.

5.6.1 CGI Action Lines

5.6.1.1 Status

        Status  =  SIP-Version 3*digit SP reason-phrase NL

   This action line causes the server to generate a SIP response and
   relay it upstream towards the client.  The server MUST copy the To,
   From, Call-ID, and CSeq headers from the original request into the
   response if these headers are not specified in the script output.
   The server SHOULD copy any other headers from the request which would
   normally be copied in the response if these are not specified in the
   script output.

   For compatibility with HTTP CGI, a server MAY interpret a message
   containing a Content-Type header field and no action line as though
   it contained "SIP/2.0 200 OK".  This usage is deprecated.

5.6.1.2 Proxy Request

        Proxy-Request  =  "CGI-PROXY-REQUEST" SIP-URL SIP-Version

   This action line causes the server to forward a request to the
   specified SIP URI.  It may be sent either by a script triggered by a
   request, in which case the triggering request is forwarded; or by a
   script triggered by a response on a server which is running
   statefully, in which case the initial request of the transaction is
   sent.

   Any SIP header field MAY be specified below the action line.
   Specified SIP headers replace all those in the original message in
   their entirety; if a script wants to preserve header elements from
   the original message as well as adding new ones, it can concatenate
   them by the usual rules of header concatenation, and place the result
   in the script output.  New header fields are added to the message
   after any Via headers but before any other headers.






Lennox, et al.               Informational                     [Page 25]

RFC 3050                      CGI for SIP                   January 2001


   Any headers from the original request which are not generated by the
   CGI script are copied into the proxied request, after modifications
   normally performed by a proxy server.  In particular, the server MUST
   append a Via field and decrement Max-Forwards.  A server MAY perform
   additional modifications as it sees fit, such as adding a Record-
   Route header.  A server SHOULD NOT append these headers if they are
   specified in the script output.

   A script MAY specify that a SIP header is to be deleted from the
   message by using the CGI-Remove CGI header; see section 5.6.2.

   If the message does not specify a body, the body from the initial
   request is used.  A message with "Content-Length: 0" is specifying an
   empty body; this causes the body to be deleted from the message.

   If the original request was authenticated by any means other than
   `basic,' the script SHOULD NOT add, change, or remove any end-to-end
   headers, as this would break the authentication.

5.6.1.3 Forward Response

        Forward-Response  =  "CGI-FORWARD-RESPONSE" Response-Name
                              SIP-Version
        Response-Name     =  response-token | "this"

   This action line causes the server to forward a response on to its
   appropriate final destination.  The same rules apply for accompanying
   SIP headers and message bodies as for CGI-PROXY-REQUEST.

   The specified response name may either be a response token the server
   previously submitted in a RESPONSE_TOKEN metavariable, or the string
   "this." The string "this" may only be sent if the message which
   triggered this CGI script was a response; it indicates that this
   triggering response should be forwarded.

5.6.1.4 Script Cookie

        Script-Cookie  =  "CGI-SET-COOKIE" token SIP-Version

   This action line causes the server to store a script cookie, passed
   as a token in the action line.  Subsequent script invocations for
   messages within the same transaction carry the token in a meta-
   header.  The script can alter the value of the cookie by subsequent
   script cookie actions.  This alteration will take affect for all
   subsequent script invocations.






Lennox, et al.               Informational                     [Page 26]

RFC 3050                      CGI for SIP                   January 2001


5.6.1.5 CGI Again

        CGI-Again  =  "CGI-AGAIN" ("yes" | "no") SIP-Version

   This action line determines whether the script will be invoked for
   subsequent requests and responses for this transaction.  If the
   parameter "yes" is given to this action, the script will be executed
   again when the next message arrives.  If the parameter is "no," or
   this action is not specified, the script will not be executed again,
   and the server will perform its default action for all subsequent
   messages.

5.6.1.6 Default Action

   If none of the actions CGI-PROXY-REQUEST, CGI-FORWARD-RESPONSE, or a
   new response are performed -- that is to say, the script outputs only
   CGI-AGAIN, CGI-SET-COOKIE, or nothing -- the script performs its
   default action.  The default action to take depends on the event
   which triggered the script:

         Request received: When the request is first received, the
               default action of the server is to check whether the
               domain of the server matches the domain of the Request-
               URI.  If it does not, the request is proxied to the
               request in the Request-URI.  Otherwise, the server checks
               its registration database against the request, and either
               proxies or redirects the request based on the action
               specified by the user agent in the registration.

         Proxied response received: If a response is received to a
               proxied request, the server forwards the response towards
               the caller if the response was a 200 or 600 class
               response, and sends a CANCEL on all pending branches.  If
               the response was 100 class, the state machinery for that
               branch is updated, and the response is proxied upstream
               towards the caller unless the it was a 100 response, not
               some other 1xx.  For 300, 400, and 500 class responses,
               an ACK is sent, and the response is forwarded upstream
               towards the caller if all other branches have terminated,
               and the response is the best received so far.  If not all
               branches have terminated, the server does nothing.  If
               all branches have terminated, but this response is not
               the best, the best is forwarded upstream.  This is the
               basic algorithm outlined in the SIP specification.







Lennox, et al.               Informational                     [Page 27]

RFC 3050                      CGI for SIP                   January 2001


5.6.2 CGI Header Fields

   CGI header fields syntactically resemble SIP header fields, but their
   names all begin with the string "CGI-".  The SIP server MUST strip
   all CGI header fields from any message before sending it, including
   those it does not recognize.

   CGI header fields have the generic syntax specified in section 6.6 of
   the SIP/2.0 specification [2].  The field-name is not case sensitive;
   the field value MUST conform to the grammar of that specific field in
   the specification where it is defined.

5.6.2.1 Request-Token

        Request-Token  =  "CGI-Request-Token" ":" token

   To assist in matching responses to proxied requests, the script can
   place a CGI-Request-Token CGI header in a CGI-PROXY-REQUEST or new
   request.  This header contains a token, opaque to the server.  When a
   response to this request arrives, the token is passed back to the
   script as a meta-header.

        This allows scripts to "fork" a proxy request, and
        correlate which response corresponds to which branch of the
        request.

5.6.2.2 Remove

        Remove  =  "CGI-Remove" ":" 1#field-name

   The CGI-Remove header allows the script to remove SIP headers from
   the outgoing request or response.  The value of this header is a
   comma-separated list of SIP headers which should be removed before
   sending out the message.

   A script MAY specify headers which are not in the request; the server
   SHOULD silently ignore these.  A script SHOULD NOT both specify a SIP
   header in its output and also list that header in a CGI-Remove
   header; the result of doing this is undefined.

5.7 Local Expiration Handling

   If a CGI script specifies an Expires header field along with CGI-
   PROXY-REQUEST, the SIP server SHOULD track the expiration timeout
   locally as well as sending the message to the remote server.  When
   the timeout expires, the server SHOULD generate a "408 Request





Lennox, et al.               Informational                     [Page 28]

RFC 3050                      CGI for SIP                   January 2001


   Timeout" response.  The timeout response SHOULD be handled as
   specified in section 5.8.  At the time the request is timed out, the
   server SHOULD also transmit CANCEL messages for the request.

        This allows a SIP CGI script in a proxy server to implement
        services like "Call Forward No Answer" to trigger after a
        user-determined time, even if the remote user-agent server
        is not responding or does not properly handle the Expires
        header field.

5.8 Locally-Generated Responses

   In a proxy environment, locally-generated responses such as "408
   Request Timeout" SHOULD be sent to the CGI script in the same manner
   as received messages are.  However, messages which merely report a
   problem with a message, such as "400 Bad Request", SHOULD NOT be.

        This is the other half of the requirements for the
        implementation of the "Call Forward No Answer" service,
        along with the local handling of the Expires header.

5.9 SIP CGI and REGISTER

   The specific semantics of a SIP CGI script which is triggered by a
   REGISTER request are somewhat different than that of those triggered
   by call-related requests; however, allowing user control of
   registration may in some cases be useful.  The two specific actions
   for REGISTER that need to be discussed are the response "200" and the
   default action.  In the former