Internet Engineering Task Force                                   SIP WG
Internet Draft                                            H. Schulzrinne
                                                     Columbia University
                                                                 D. Oran
                                                                   Cisco
                                                            G. Camarillo
                                                                Ericsson
draft-schulzrinne-sip-reason-01.txt
February 28, 2002
Expires: August 2002


      The Reason Header Field for the Session Initiation Protocol

STATUS OF THIS MEMO

   This document is an Internet-Draft and is in full conformance with
   all provisions of Section 10 of RFC2026.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as Internet-
   Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress".

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt

   To view the list Internet-Draft Shadow Directories, see
   http://www.ietf.org/shadow.html.


Abstract

   For creating services, it is often useful to know why a SIP request
   was issued. This document defines an optional informational header
   field, Reason, that provides this information.










H. Schulzrinne et. al.                                        [Page 1]


Internet Draft                    SIP                  February 28, 2002





                           Table of Contents



   1          Introduction ........................................    3
   1.1        Terminology .........................................    3
   2          The Reason Request Header Field .....................    3
   3          IANA Considerations .................................    5
   4          Security Considerations .............................    5
   5          Acknowledgments .....................................    5
   6          Authors' Addresses ..................................    5
   7          Bibliography ........................................    6




































H. Schulzrinne et. al.                                        [Page 2]


Internet Draft                    SIP                  February 28, 2002


1 Introduction

   The same SIP [1] request can be issued for a variety of reasons. For
   example, a SIP CANCEL request can be issued if the call has completed
   on another branch or was abandoned before answer. While the protocol
   and system behavior is the same in both cases, namely, alerting will
   cease, the user interface may well differ. In the second case, the
   call may be logged as a missed call, while this would not be
   appropriate if the call was picked up elsewhere.

   Third party call controllers sometimes generate a SIP request upon
   reception of a SIP response from another dialog. Gateways generate
   SIP requests after receiving messages from a different protocol than
   SIP.  In both cases the client may be interested in knowing what
   triggered the SIP request.

   SIP responses already have a means of informing the user of why a
   request failed. The simple mechanism in this draft accomplishes
   something roughly similar for requests.

   Initially, the request header field defined here appears to be most
   useful for BYE and CANCEL requests, but it can appear in any requests
   and in any response.

   Clients and servers are free to ignore this header. It has no impact
   on protocol processing.

1.1 Terminology

   In this document, the key words "MUST", "MUST NOT", "REQUIRED",
   "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
   and "OPTIONAL" are to be interpreted as described in RFC 2119 [2] and
   indicate requirement levels for compliant SIP implementations.

2 The Reason Request Header Field

   The Reason header field can appear in any request or response. The
   syntax of the header field follows the standard SIP parameter syntax.



        Reason            =  "Reason" HCOLON reason-code *(SEMI reason-params)
        reason-code       =  1*DIGIT
        reason-params     =  triggered-by | protocol-cause | reason-text
                             | reason-extension
        triggered-by      =  "triggered" EQUAL quoted-string
        protocol-cause    =  "cause" EQUAL cause
        cause             =  1*DIGIT



H. Schulzrinne et. al.                                        [Page 3]


Internet Draft                    SIP                  February 28, 2002


        reason-text       =  "text" EQUAL quoted-string
        reason-extension  =  generic-param


   Examples are:

     Reason: 1 ;text="Call completed elsewhere"
     Reason: 4 ;triggered="Q.850" ;cause=16 ;text="Terminated"
     Reason: 7 ;triggered="SIP/2.0" ;cause=600 ;text="Busy Everywhere"
     Reason: 8 ;triggered="SIP/2.0" ;cause=580
               ;text="Precondition Failure"



   The following reason codes and text phrases have been defined:

        1.   (Call completed elsewhere): CANCEL request; another branch
             completed the call.

        2.   (Abandoned): CANCEL request; the call attempt was
             abandoned.

        3.   (Timed out): CANCEL request; the call attempt timed out.

        4.   (Terminated): BYE request; the caller or callee terminated
             the call.

        5.   (Transfer completed): BYE request; the call transfer was
             completed.

        6.   (No media): BYE request; the call was terminated since the
             other side did not receive media for an extended period of
             time.

        7.   (Interworking): BYE and CANCEL requests and any final
             response; the call was terminated because a gateway or a
             third party call controller received an error or a release
             message from the other side. This reason code SHOULD only
             be used if none of the other reason codes is applicable.

        8.   (Offer refused): BYE and CANCEL request; an offer that the
             client wanted to refuse was received in a response. The
             user agent client terminates the session.

        9.   (Update requested): 155 response; the Reason header field
             contains the status code of the final response that
             triggered the 155 response.




H. Schulzrinne et. al.                                        [Page 4]


Internet Draft                    SIP                  February 28, 2002


   The text phrase MAY be modified, e.g., translated into different
   languages or enhanced with additional call-specific information, for
   example,

     Reason: 2 ;text="Anrufer gab nach 30 Sekunden auf"



   The following values for the triggered parameter have been defined:

        SIP/2.0: The cause parameter contains a SIP status code.

        Q.850: The cause parameter contains an ITU-T Q.850 cause value
             in decimal representation.

   The default value is "SIP/2.0".

   Proxies generating a CANCEL request upon reception of a CANCEL from
   the previous hop that contains a Reason header field SHOULD copy it
   into the new CANCEL request.

3 IANA Considerations

   IANA registers new reason codes. All new reason codes MUST be defined
   in an RFC.

   IANA also registers new values for the triggered parameter. These
   values MUST refer to either an ITU-T Recommendation number, an IETF
   protocol name or the recognized protocol identifier from another
   standardization organization.

4 Security Considerations

   While spoofing or removing the Reason header field has no impact on
   protocol operation, the user interface may change and end systems may
   provide services based on this header field. Thus, it is RECOMMENDED
   that this field is protected by a suitable integrity mechanism.

5 Acknowledgments

   Jonathan Rosenberg provided helpful comments and suggestions.

6 Authors' Addresses

   Henning Schulzrinne
   Dept. of Computer Science
   Columbia University
   1214 Amsterdam Avenue



H. Schulzrinne et. al.                                        [Page 5]


Internet Draft                    SIP                  February 28, 2002


   New York, NY 10027
   USA
   electronic mail: schulzrinne@cs.columbia.edu

   David R. Oran
   Cisco Systems, Inc.
   Acton, MA
   USA
   electronic mail: oran@cisco.com

   Gonzalo Camarillo
   Ericsson
   Advanced Signalling Research Lab.
   FIN-02420 Jorvas
   Finland
   electronic mail: Gonzalo.Camarillo@ericsson.com

7 Bibliography

   [1] M. Handley, H. Schulzrinne, E. Schooler, and J. Rosenberg, "SIP:
   session initiation protocol," Request for Comments 2543, Internet
   Engineering Task Force, Mar. 1999.

   [2] S. Bradner, "Key words for use in RFCs to indicate requirement
   levels," Request for Comments 2119, Internet Engineering Task Force,
   Mar. 1997.


   Full Copyright Statement

   Copyright (c) The Internet Society (2002). All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works. However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.



H. Schulzrinne et. al.                                        [Page 6]


Internet Draft                    SIP                  February 28, 2002


   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.













































H. Schulzrinne et. al.                                        [Page 7]