\section{How-To initiate, modify or terminate calls.}
\label{group__howto1__initialize}\index{How-To initiate, modify or terminate calls.@{How-To initiate, modify or terminate calls.}}
eXosip2 offers a flexible API to help you controling calls.

\subsubsection*{Initiate a call}

To start an outgoing call, you typically need a few headers which will be used by eXosip2 to build a default SIP INVITE request. The code below is used to start a call:

\small\begin{alltt}
  osip\_message\_t *invite;
  int i;\end{alltt}
\normalsize 


\small\begin{alltt}  i = eXosip\_call\_build\_initial\_invite (\&invite, "<sip:to@antisip.com>",
                                        "<sip:from@antisip.com>",
                                        NULL, // optionnal route header
                                        "This is a call for a conversation");
  if (i != 0)
    \{
      return -1;
    \}\end{alltt}
\normalsize 


\small\begin{alltt}  osip\_message\_set\_supported (invite, "100rel");\end{alltt}
\normalsize 


\small\begin{alltt}  \{
    char tmp[4096];
    char localip[128];\end{alltt}
\normalsize 


\small\begin{alltt}    eXosip\_guess\_localip (AF\_INET, localip, 128);
    snprintf (tmp, 4096,
              "v=0\(\backslash\)r\(\backslash\)n"
              "o=josua 0 0 IN IP4 %s\(\backslash\)r\(\backslash\)n"
              "s=conversation\(\backslash\)r\(\backslash\)n"
              "c=IN IP4 %s\(\backslash\)r\(\backslash\)n"
              "t=0 0\(\backslash\)r\(\backslash\)n"
              "m=audio %s RTP/AVP 0 8 101\(\backslash\)r\(\backslash\)n"
              "a=rtpmap:0 PCMU/8000\(\backslash\)r\(\backslash\)n"
              "a=rtpmap:8 PCMA/8000\(\backslash\)r\(\backslash\)n"
              "a=rtpmap:101 telephone-event/8000\(\backslash\)r\(\backslash\)n"
              "a=fmtp:101 0-11\(\backslash\)r\(\backslash\)n", localip, localip, port);
    osip\_message\_set\_body (invite, tmp, strlen (tmp));
    osip\_message\_set\_content\_type (invite, "application/sdp");
  \}\end{alltt}
\normalsize 


\small\begin{alltt}  eXosip\_lock ();
  i = eXosip\_call\_send\_initial\_invite (invite);
  if (i > 0)
    \{
      eXosip\_call\_set\_reference (i, reference);
    \}
  eXosip\_unlock ();
  return i;\end{alltt}
\normalsize 


\small\begin{alltt}\end{alltt}
\normalsize 


The above code is using eXosip\_\-call\_\-build\_\-initial\_\-invite to build a default SIP INVITE request for a new call. You have to insert a SDP body announcing your audio parameter for the RTP stream.

The above code also show the flexibility of the eXosip2 API which allow you to insert additionnal headers such as \char`\"{}Supported: 100rel\char`\"{} (announcing support for a SIP extension). Thus you can enterely control the creation of SIP requests.

The returned element of eXosip\_\-call\_\-send\_\-initial\_\-invite is the call identifier that you can use to send a CANCEL. In future events other than 100 Trying, you'll also get the dialog identifier that will also be needed to control established calls.

eXosip\_\-call\_\-set\_\-reference is also a mean to attach one of your own context to a call so that you'll get your pointer back in \doxyref{eXosip\_\-event}{p.}{structeXosip__event}.

\subsubsection*{Answer a call}

The code below is another example that teach you how to answer an incoming call.

You'll usually need to send a \char`\"{}180 Ringing\char`\"{} SIP answer when receiving a SIP INVITE:

\small\begin{alltt}
  eXosip\_lock ();
  eXosip\_call\_send\_answer (ca->tid, 180, NULL);
  eXosip\_unlock ();
\end{alltt}
\normalsize 


{\bf Note}: The above code also shows that the stack is sometimes able to build and send a default SIP messages with only one API call

Then, when the user wants to answer the call, you'll need to send a 200 ok and insert a SDP body in your SIP answer:

\small\begin{alltt}
  osip\_message\_t *answer = NULL;\end{alltt}
\normalsize 


\small\begin{alltt}  eXosip\_lock ();
  i = eXosip\_call\_build\_answer (ca->tid, 200, \&answer);
  if (i != 0)
  \{
     eXosip\_call\_send\_answer (ca->tid, 400, NULL);
  \}
  else
  \{
     i = sdp\_complete\_200ok (ca->did, answer);
     if (i != 0)
     \{
        osip\_message\_free (answer);
        eXosip\_call\_send\_answer (ca->tid, 415, NULL);
     \}
     else
        eXosip\_call\_send\_answer (ca->tid, 200, answer);
  \}
  eXosip\_unlock ();
\end{alltt}
\normalsize 


{\bf Note}: In the above code, you can note that to send a response to a request, you have to use the transaction identifier (and not a call identifier or a dialog identifier!)

{\bf Note2}: For sending a 200ok, you'll usually need to insert a SDP body in the answer and before this, to negotiate the parameters and codecs that you want to support. In the test tool, provided by eXosip2 (josua application), you'll find a very basic implementation of the SDP negotiation.

\subsubsection*{Sending other request}

The call control API allows you to send and receive REFER, UPDATE, INFO, OPTIONS, NOTIFY and INVITEs whitin calls. A few limitations still exist for answering other requests within calls, but it should be already possible to send any kind of request.

Here you have a code sample to send an INFO requests used to send an out of band dtmf within the signalling layer.

\small\begin{alltt}
  osip\_message\_t *info;
  char dtmf\_body[1000];
  int i;\end{alltt}
\normalsize 


\small\begin{alltt}  eXosip\_lock ();
  i = eXosip\_call\_build\_info (ca->did, \&info);
  if (i == 0)
  \{
     snprintf (dtmf\_body, 999, "Signal=%c\(\backslash\)r\(\backslash\)nDuration=250\(\backslash\)r\(\backslash\)n", c);
     osip\_message\_set\_content\_type (info, "application/dtmf-relay");
     osip\_message\_set\_body (info, dtmf\_body, strlen (dtmf\_body));
     i = eXosip\_call\_send\_request (ca->did, info);
  \}
  eXosip\_unlock ();
\end{alltt}
\normalsize