rfc3050.txt

最新的RFC

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


   In a SIP server, the model is different, and is depicted in Figure 2.


     ~~~~~~~~   req  -------   req   -------     req   ~~~~~~~~
    |        |------|       |-------|       |---------|        |
    | client | resp | server| resp  | server| resp    | client |
    |        |------|       |-------|       |---------|        |
     ~~~~~~~~        -------         -------           --------
                      |   | CGI
                      |   |
                     -------
                    |       |
                    |  CGI  |
                    | prog. |
                    |       |
                     -------

   Figure 2: SIP CGI Model

   The client generates a request, which is forwarded to a server.  The
   server may generate a response (such as an error or redirect
   response).  Or, if the server is a proxy server, the request is
   proxied to another server, and eventually to a user agent, and the
   response is passed back upstream, through the server, and back
   towards the client.  A SIP proxy server may additionally fork
   requests, generating multiple requests in response to a received
   request.  Generally, a proxy server will not generate the content in
   responses.  These contain session descriptions created by user
   agents.  Services, such as call forward and mobility services, are
   based on the decisions the server makes about (1) when, to where, and
   how many requests to proxy downstream, and (2) when to send a
   response back upstream.  Creation of services such as ad-hoc bridging
   (where the server acts as a media mixer in a multiparty call, without
   being asked to do so by the end users) will require the server to
   generate new requests of its own, and for it to modify and generate
   the body in responses.

   An HTTP server is mainly concerned about generation of responses.  A
   SIP server is generally concerned about performing four basic
   operations:

        Proxying of Requests: Receiving a request, adding or modifying
             any of the headers, deciding on a set of servers to forward
             the request to, and forwarding it to them.

        Returning Responses: Receiving a response, adding or modifying
             any of the headers, and passing the response towards the
             client.



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


        Generating Requests: Creating a new request, originating at the
             server, placing headers and a body into the message, and
             sending it to a server.

        Generation of Responses: Receiving a request, generating a
             response to it, and sending it back to the client.

   When a request is received, one or more of the above operations may
   occur at once.  For example, a SIP server may generate a provisional
   response, generate a new request, and proxy the original request to
   two servers.  This implies that SIP CGI must encompass a greater set
   of functions than HTTP CGI.  These functions are a super-set of the
   simple end-server request/response model.

3.2 Persistence Model

   In HTTP CGI, a script is executed once for each request.  It
   generates the response, and then terminates.  There is no state
   maintained across requests from the same user, as a general rule
   (although this can be done -- and is -- for more complex services
   such as database accesses, which essentially encapsulate state in
   client-side cookies or dynamically-generated URLs).  A transaction is
   just a single request, and a response.

   In SIP CGI, since a request can generate many new and proxied
   requests, these themselves will generate responses.  A service will
   often require these responses to be processed, and additional
   requests or responses to be generated.  As a result, whereas an HTTP
   CGI script executes once per transaction, a SIP CGI script must
   maintain control somehow over numerous events.

   In order to enable this, and to stay with the original CGI model, we
   mandate that a SIP CGI script executes when a message arrives, and
   after generating output (in the form of additional messages),
   terminate.  State is maintained by allowing the CGI to return an
   opaque token to the server.  When the CGI script is called again for
   the same transaction, this token is passed back to the CGI script.
   When called for a new transaction, no token is passed.

   For example, consider a request which arrives at a SIP server.  The
   server calls a CGI script, which generates a provisional response and
   a proxied request.  It also returns a token to the server, and then
   terminates.  The response is returned upstream towards the client,
   and the request is proxied.  When the response to the proxied request
   arrives, the script is executed again.  The environment variables are
   set based on the content of the new response.  The script is also
   passed back the token.  Using the token as its state, the script
   decides to proxy the request to a different location.  It therefore



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


   returns a proxied request, and another token.  The server forwards
   this new request, and when the response comes, calls the CGI script
   once more, and passes back the token.  This time, the script
   generates a final response, and passes this back to the server.  The
   server sends the response to the client, destroys the token, and the
   transaction is complete.

3.3 SIP CGI Triggers

   In many cases, calling the CGI script on the reception of every
   message is inefficient.  CGI scripts come at the cost of significant
   overhead since they generally require creation of a new process.
   Therefore, it is important in SIP CGI for a script to indicate, after
   it is called the first time, under what conditions it will be called
   for the remainder of the transaction.  If the script is not called,
   the server will take the "default" action, as specified in this
   document.  This allows an application designer to trade off
   flexibility for computational resources.  Making an analogy to the
   Intelligent Network (IN) - a script is able to define the triggers
   for its future execution.

   So, in summary, whereas an HTTP CGI script executes once during a
   transaction, a single SIP CGI script may execute many times during a
   transaction, and may specify at which points it would like to have
   control for the remainder of the transaction.

3.4 Naming

   In HTTP CGI, the CGI script itself is generally the resource named in
   the request URI of the HTTP request.  This is not so in SIP.  In
   general, the request URI names a user to be called.  The mapping to a
   script to be executed may depend on other SIP headers, including To
   and From fields, the SIP method, status codes, and reason phrases.
   As such, the mapping of a message to a CGI script is purely a matter
   of local policy administration at a server.  A server may have a
   single script which always executes, or it may have multiple scripts,
   and the target is selected by some parts of the header.

3.5 Environment Variables

   In HTTP CGI, environment variables are set with the values of the
   paths and other aspects of the request.  As there is no notion of a
   path in SIP, some of these environment variables do not make sense.








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


3.6 Timers

   In SIP, certain services require that the script gets called not only
   when a message arrives, but when some timer expires.  The classic
   example of this is "call forward no answer." To be implemented with
   SIP CGI, the first time the script is executed, it must generate a
   proxied request, and also indicate a time at which to be called again
   if no response comes.  This kind of feature is not present in HTTP
   CGI, and some rudimentary support for it is needed in SIP CGI.

4 Overview of SIP CGI

   When a request arrives at a SIP server, initiating a new transaction,
   the server will set a number of environment variables, and call a CGI
   script.  The script is passed the body of the request through stdin.

   The script returns, on stdout, a set of SIP action lines, each of
   which may be modified by CGI and/or SIP headers.  This set is
   delimited through the use of two carriage returns.  The action lines
   allow the script to specify any of the four operations defined above,
   in addition to the default operation.  Generating a response is done
   by copying the the status line of the response into an action line of
   the CGI output.  For example, the following will create a 200 OK to
   the original request:

   SIP/2.0 200 OK

   The operation of proxying a request is supported by the CGI-PROXY-
   REQUEST CGI action, which takes the URL to proxy to as an argument.
   For example, to proxy a request to [e-mail]:

   CGI-PROXY-REQUEST sip:[e-mail] SIP/2.0
   Contact: sip:[e-mail]

   In this example, the server will take the original request, and
   modify any header fields normally changed during the proxy operation
   (such as decrementing Max-Forwards, and adding a Via field).  This
   message is then "merged" with the output of the CGI script - SIP
   headers specified below the action line in the CGI output will be
   added to the outbound request.  In the above example, the Contact
   header will be added.  Note that the action line looks like the
   request line of a SIP request message.  This is done in order to
   simplify parsing.

   To delete headers from the outgoing request, the merge process also
   supports the CGI header CGI-Remove.  Like SIP headers, CGI headers
   are written underneath the action line.  They are extracted by the
   SIP server, and used to provide the server with additional guidance.



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


   CGI headers always begin with CGI to differentiate them from SIP
   headers.  In this case, the supported values for the CGI-Remove
   header are the names of headers in the original message.

   Returning of responses is more complex.  A server may receive
   multiple responses as the result of forking a request.  The script
   should be able to ask the server to return any of the responses it
   had received previously.  To support this, the server will pass an
   opaque token to the script through environment variables, unique for
   each response received.  To return a response, a CGI script needs to
   indicate which response is to be returned.  For example, to return a
   response named with the token abcdefghij, the following output is
   generated:

   CGI-FORWARD-RESPONSE abcdefghij SIP/2.0

   Finally, if the script does not output any of the above actions, the
   server does what it would normally do upon receiving the message that
   triggered the script.

   A SIP CGI script is normally only executed when the original request
   arrives.  If the script also wants to be called for subsequent
   messages in a transaction -- due to responses to proxied requests, or
   (in certain circumstances) ACK and CANCEL requests, it can perform
   the CGI-AGAIN action:

   CGI-AGAIN yes SIP/2.0

   This action applies only to the next invocation of the script; it
   means to invoke the script one more time.  Outputting "no" is
   identical to outputting "yes" on this invocation of the script and
   outputting nothing the next time the script is called.

   When the script is re-executed, it may need access to some state in
   order to continue processing.  A script can generate one piece of
   state, called a cookie, for any new request or proxied request.  It
   is passed to the server through the CGI-SET-COOKIE action.  The
   action contains a token, which is the cookie itself.  The server does
   not examine or parse the cookie.  It is simply stored.  When the
   script is re-executed, the cookie is passed back to the script
   through an environment variable.

   CGI-SET-COOKIE khsihppii8asdl SIP/2.0

   Finally, when the script causes the server to proxy a request,
   responses to these requests will arrive.  To ease matching of
   responses to requests, the script can place a request token in the
   CGI CGI-Request-Token header.  This header is removed by the server



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


   when the request is proxied.  Any responses received to this request
   will have the token passed in an environment variable.

5 SIP CGI Specification

5.1 Introduction

5.1.1 Relationship with HTTP CGI

   This SIP CGI specification is based on work-in-progress revision 1.1
   of the HTTP CGI specification [1].  That document is a product of the
   CGI-WG mailing list, which is not an official IETF working group.
   CGI-WG's homepage is located at the URL
   http://Web.Golux.Com/coar/cgi/, and the most recent versions of the
   CGI specification are available there.  This specification
   incorporates a great deal of text from the work-in-progress version
   of that document as of February 23, 2000.  A future version of this
   specification may be changed to cite parts of that document by
   reference instead.