\documentclass[11pt]{article}
\usepackage{i-d,l2xtools}

\newcommand{\INVITE}{\textsf{INVITE}}
\newcommand{\BYE}{\textsf{BYE}}
\newcommand{\ACK}{\textsf{ACK}}
\newcommand{\CANCEL}{\textsf{CANCEL}}
\newcommand{\OPTIONS}{\textsf{OPTIONS}}
\newcommand{\REGISTER}{\textsf{REGISTER}}
\newcommand{\header}[1]{\textsf{#1}}
\newcommand{\host}[1]{\texttt{#1}}

\pubdate{\today}
\expires{August 2002}
\filename{draft-schulzrinne-sip-reason-01}
\title{The Reason Header Field for the Session Initiation Protocol}
\author{H. Schulzrinne, D. Oran, G. Camarillo}
\address{Columbia University, Cisco, Ericsson}
\shorttitle{SIP}
\wg{SIP WG}
\begin{document}
\maketitle

\status{}

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

\tableofcontents
\txtinserttocspace{2}{1}

\section{Introduction}
\label{sec:intro}

The same SIP \cite{rfc2543} 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.

\subsection{Terminology}
\label{sec:terminology}

In this document, the key words ``{\MUST}'', ``{\MUSTNOT}'',
``{\REQUIRED}'', ``{\SHALL}'', ``{\SHALLNOT}'', ``{\SHOULD}'',
``{\SHOULDNOT}'', ``{\RECOMMENDED}'', ``{\MAY}'', and ``{\OPTIONAL}''
are to be interpreted as described in RFC 2119 \cite{rfc2119} and
indicate requirement levels for compliant SIP implementations.

\section{The \header{Reason} Request Header Field}

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

\begin{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\\
reason-text       & = & "text" EQUAL quoted-string\\
reason-extension  & = & generic-param\\
\end{syntax}

Examples are:
\begin{verbatim}
  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"
\end{verbatim}

The following reason codes and text phrases have been defined:

\begin{enumerate}
\item (Call completed elsewhere): {\CANCEL} request; another
branch completed the call.

\item (Abandoned): {\CANCEL} request; the call attempt was
abandoned.

\item (Timed out): {\CANCEL} request; the call attempt timed out.

\item (Terminated): {\BYE} request; the caller or callee
terminated the call.

\item (Transfer completed): {\BYE} request; the call
transfer was completed.

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

\item (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.

\item (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.

\item (Update requested): 155 response; the Reason header field contains the status code of the final response that triggered the 155 response.
\end{enumerate}

The text phrase {\MAY} be modified, e.g., translated into different
languages or enhanced with additional call-specific information, for
example,
\begin{verbatim}
  Reason: 2 ;text="Anrufer gab nach 30 Sekunden auf"
\end{verbatim}

The following values for the \header{triggered} parameter have been
defined:
\begin{description}
\item[SIP/2.0:] The cause parameter contains a SIP status code.

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

\end{description}

The default value is ``SIP/2.0''.

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

\section{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.

\section{Security Considerations}

While spoofing or removing the \header{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.

\section{Acknowledgments}

Jonathan Rosenberg provided helpful comments and suggestions.

\section{Authors' Addresses}

\begin{flushleft}
Henning Schulzrinne\\
Dept. of Computer Science\\
Columbia University\\
1214 Amsterdam Avenue\\
New York, NY 10027\\
USA\\
electronic mail: {\sf schulzrinne@cs.columbia.edu}
\end{flushleft}

\begin{flushleft}
David R. Oran\\
Cisco Systems, Inc.\\
Acton, MA\\
USA\\ 
electronic mail: {\sf oran@cisco.com}
\end{flushleft}

\begin{flushleft}
Gonzalo Camarillo\\
Ericsson\\
Advanced Signalling Research Lab.\\
FIN-02420 Jorvas\\
Finland\\
electronic mail:  {\sf Gonzalo.Camarillo@ericsson.com}
\end{flushleft}

\bibliographystyle{ieeetr}
\bibliography{string,i-d,rfc}

\input{../copyright}

\end{document}
