### eXosip_listen_addr usage example

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_setup.md

Example demonstrating how to open UDP and TLS transports using eXosip_listen_addr.

```c
if (eXosip_listen_addr(ctx, IPPROTO_UDP, NULL, 5060, AF_INET, 0) != 0) {
    fprintf(stderr, "could not open UDP transport\n");
    eXosip_quit(ctx);
    exit(1);
}
/* TLS, secure call */
if (eXosip_listen_addr(ctx, IPPROTO_TCP, NULL, 5061, AF_INET, 1) != 0)
    fprintf(stderr, "could not open TLS transport\n");
```

--------------------------------

### Usage example of eXosip_register_build_initial_register_withqvalue

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_register.md

Example showing how to initialize the message pointer and call the function to build a registration request.

```c
osip_message_t *reg = NULL;
int rid = eXosip_register_build_initial_register_withqvalue(ctx,
             "sip:bob@example.com", "example.com", NULL, 3600, "0.5", &reg);
if (rid < 0) return;   /* error handling as above */
```

--------------------------------

### Managing authentication credentials example

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_event.md

Example demonstrating how to add credentials, rotate a password by removing the old entry, and adding a new one.

```c
if (eXosip_add_authentication_info(ctx, "alice", "alice", "s3cret", NULL, NULL) != 0)
    fprintf(stderr, "credentials rejected\n");
/* ... later: rotate password ... */
eXosip_remove_authentication_info(ctx, "alice", NULL);
eXosip_add_authentication_info(ctx, "alice", "alice", "newpass", NULL, NULL);
```

--------------------------------

### Build and send an OPTIONS request

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_options.md

Example of building an OPTIONS request, adding capabilities, and sending it.

```c
osip_message_t *opts = NULL;
if (eXosip_options_build_request(ctx, &opts,
        "sip:proxy.example.com", "sip:alice@example.com", NULL) != 0)
    return;
osip_message_set_allow(opts, "INVITE, ACK, CANCEL, OPTIONS, BYE, MESSAGE");
if (eXosip_options_send_request(ctx, opts) != 0)
    fprintf(stderr, "OPTIONS send failed\n");
```

--------------------------------

### Build and send an OPTIONS answer

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_options.md

Example of building and sending an answer within an event loop on EXOSIP_MESSAGE_NEW.

```c
/* inside the event loop, on EXOSIP_MESSAGE_NEW with an OPTIONS request */
osip_message_t *answer = NULL;
if (eXosip_options_build_answer(ctx, ev->tid, 200, &answer) == 0) {
    osip_message_set_allow(answer, "INVITE, ACK, BYE, OPTIONS, INFO, MESSAGE");
    eXosip_options_send_answer(ctx, ev->tid, 200, answer);
}
```

--------------------------------

### Asynchronous NAPTR lookup example

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_setup.md

Example of initiating an asynchronous NAPTR lookup and waiting for the final result using eXosip_dnsutils_dns_process.

```c
/* start an async NAPTR lookup for sip.example.com/SIP/UDP */
struct osip_naptr *n = eXosip_dnsutils_naptr(ctx, "sip.example.com", "sip", "UDP", 1);
if (n != NULL) {
    eXosip_dnsutils_dns_process(n, 1);   /* wait for the final answer */
}
```

--------------------------------

### DTMF via INFO Example

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_call.md

Example showing how to build and send an INFO request with a DTMF relay body.

```APIDOC
## DTMF via INFO Example

### Description
Example showing how to build and send an INFO request with a DTMF relay body.

### Code
```c
osip_message_t *info = NULL;
if (eXosip_call_build_info(ctx, ev->did, &info) == 0) {
    char body[64];
    snprintf(body, sizeof(body), "Signal=%c\r\nDuration=250\r\n", '5');
    osip_message_set_content_type(info, "application/dtmf-relay");
    osip_message_set_body(info, body, strlen(body));
    if (eXosip_call_send_request(ctx, ev->did, info) != 0)
        fprintf(stderr, "INFO send failed\n");
}
```
```

--------------------------------

### eXosip_guess_localip usage example

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_setup.md

Example of using eXosip_guess_localip to populate a local IP address into an SDP message buffer.

```c
char localip[128];
if (eXosip_guess_localip(ctx, AF_INET, localip, sizeof(localip)) == 0)
    snprintf(sdp, sizeof(sdp), "v=0\r\nc=IN IP4 %s\r\nm=audio 4000 RTP/AVP 0\r\n", localip);
```

--------------------------------

### Usage Examples

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_event.md

Examples of using the automatic action functions in threaded and monothread styles.

```APIDOC
## Usage Examples

### Threaded style
```c
/* threaded style: let the stack do the housekeeping */
for (;;) {
    eXosip_event_t *ev = eXosip_event_wait(ctx, 10, 0);
    if (ev == NULL) continue;
    eXosip_automatic_action(ctx);          /* credentials, refresh, session-timer */
    switch (ev->type) { /* application logic */ }
    eXosip_event_free(ev);
}
```

### Monothread style
```c
/* monothread style: the application drives everything */
eXosip_execute(ctx);
eXosip_automatic_action(ctx);
/* when a dialog-package SUBSCRIBE arrives */
int rc = eXosip_insubscription_automatic(ctx, ev);
if (rc == OSIP_NOTFOUND)
    fprintf(stderr, "no incoming subscription for dialog %d\n", ev->did);
```
```

--------------------------------

### eXosip_find_free_port usage example

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_setup.md

Shows how to call eXosip_find_free_port to get a free RTP port starting from 4000 over UDP. The returned port and port+1 are used for RTP/RTCP.

```c
int rtp_port = eXosip_find_free_port(ctx, 4000, IPPROTO_UDP);
if (rtp_port > 0) { /* use rtp_port and rtp_port+1 for RTP/RTCP */ }
```

--------------------------------

### Building and sending a PUBLISH request

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_publish.md

Example of constructing a PUBLISH message and sending it using the eXosip context.

```c
osip_message_t *pub = NULL;
int rc = eXosip_build_publish(ctx, &pub,
             "sip:alice@example.com", "sip:alice@example.com", NULL,
             "presence", "600", "application/pidf+xml", pidf_xml);
if (rc != 0) { fprintf(stderr, "build PUBLISH failed: %d\n", rc); return; }
if (eXosip_publish(ctx, pub, "sip:alice@example.com") != 0)
    fprintf(stderr, "send PUBLISH failed\n");
```

--------------------------------

### eXosip_masquerade_contact usage examples

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_setup.md

Shows how to set a static NAT address and how to reset the configuration to auto-guess mode.

```c
eXosip_masquerade_contact(ctx, "81.2.3.4", 5060);  /* static NAT */
eXosip_masquerade_contact(ctx, NULL, 0);           /* auto mode */
```

--------------------------------

### NOTIFY Subscription State Example

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_call.md

Example showing how to build a NOTIFY request with a subscription state inside a call.

```APIDOC
## NOTIFY Subscription State Example

### Description
Example showing how to build a NOTIFY request with a subscription state inside a call.

### Code
```c
osip_message_t *notify = NULL;
int rc = eXosip_call_build_notify(ctx, did, EXOSIP_SUBCRSTATE_ACTIVE, &notify);
if (rc == 0) { /* e.g. add a PIDF body */ eXosip_call_send_request(ctx, did, notify); }
```
```

--------------------------------

### eXosip_lock and eXosip_unlock usage example

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_setup.md

Example of serializing access to the context by wrapping a send function with lock and unlock calls.

```c
eXosip_lock(ctx);
int cid = eXosip_call_send_initial_invite(ctx, invite);
eXosip_unlock(ctx);
```

--------------------------------

### Initialize eXosip TLS Context

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_setup.md

Example of initializing an eXosip_tls_ctx_t structure and applying it using eXosip_set_tls_ctx, including basic error checking.

```c
eXosip_tls_ctx_t tls = {
  "/etc/sip/random", "/etc/sip/dh.pem", "/etc/sip/ca.pem",
  { "key.pem", "secret", "cert.pem" },   /* client */
  { "skey.pem", "secret", "scert.pem" }  /* server */
};
eXosip_tls_ctx_error err = eXosip_set_tls_ctx(ctx, &tls);
if (err != TLS_OK)
    fprintf(stderr, "TLS ctx error code %d\n", err);
```

--------------------------------

### Constructing and Sending an INVITE Request

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_call.md

Example demonstrating the workflow of building an INVITE, adding an SDP body, and sending the request. The application must ensure the previous INVITE transaction is finished before calling the build function.

```c
osip_message_t *invite = NULL;
int rc = eXosip_call_build_initial_invite(ctx, &invite, "<sip:bob@example.com>",
                                          "<sip:alice@example.com>", NULL,
                                          "Let's talk");
if (rc != 0) { fprintf(stderr, "build failed: %d\n", rc); return; }

char sdp[512], localip[64];
eXosip_guess_localip(ctx, AF_INET, localip, sizeof(localip));
snprintf(sdp, sizeof(sdp),
         "v=0\r\no=j 0 0 IN IP4 %s\r\ns=-\r\nc=IN IP4 %s\r\n"
         "t=0 0\r\nm=audio 4000 RTP/AVP 0\r\na=rtpmap:0 PCMU/8000\r\n",
         localip, localip);
osip_message_set_body(invite, sdp, strlen(sdp));
osip_message_set_content_type(invite, "application/sdp");

eXosip_lock(ctx);
int cid = eXosip_call_send_initial_invite(ctx, invite);
eXosip_unlock(ctx);
if (cid < 0) { fprintf(stderr, "send failed: %d\n", cid); return; }
/* cid is now usable to CANCEL / attach app reference */
```

--------------------------------

### Send an OPTIONS request

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_options.md

Example of sending an OPTIONS request and checking for errors.

```c
int rc = eXosip_options_send_request(ctx, opts);
if (rc != 0) fprintf(stderr, "send OPTIONS failed: %d\n", rc);
```

--------------------------------

### eXosip_generate_random usage example

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_event.md

Example of calling eXosip_generate_random to fill a 32-byte buffer and printing the result to stderr on success.

```c
char branch[32];
if (eXosip_generate_random(branch, sizeof(branch)) == 0)
    fprintf(stderr, "random: %s\n", branch);
```

--------------------------------

### Building and sending an out-of-dialog MESSAGE request

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_message.md

Example showing how to build a MESSAGE request, set its content, and send it using eXosip_message_build_request and eXosip_message_send_request.

```c
osip_message_t *msg = NULL;
int rc = eXosip_message_build_request(ctx, &msg, "MESSAGE",
             "sip:bob@example.com", "sip:alice@example.com", NULL);
if (rc != 0) { fprintf(stderr, "build failed: %d\n", rc); return; }

const char *body = "Hello, this is an instant message";
osip_message_set_content_type(msg, "text/plain");
osip_message_set_body(msg, body, strlen(body));

if (eXosip_message_send_request(ctx, msg) < 0)
    fprintf(stderr, "send MESSAGE failed\n");
```

--------------------------------

### Build and send an initial REGISTER request

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_register.md

Example showing how to build an initial REGISTER request with eXosip_register_build_initial_register and send it with eXosip_register_send_register. The contact parameter is NULL, so eXosip generates the Contact header. On failure, a negative rid is returned and an error is printed.

```c
osip_message_t *reg = NULL;
int rid = eXosip_register_build_initial_register(ctx,
             "sip:alice@antisip.example.com", "sip.antisip.example.com",
             NULL, 1800, &reg);
if (rid < 0) { fprintf(stderr, "cannot build REGISTER: %d\n", rid); return; }
if (eXosip_register_send_register(ctx, rid, reg) != 0)
    fprintf(stderr, "cannot send REGISTER\n");
```

--------------------------------

### eXosip_set_cbsip_message usage example

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_setup.md

Demonstrates how to define a callback function and register it with eXosip_set_cbsip_message to monitor sent and received SIP messages.

```c
static void on_msg(osip_message_t *msg, int received) {
    fprintf(stderr, "%s: %s\n", received ? "RX" : "TX", msg->sip_method);
}
int rc = eXosip_set_cbsip_message(ctx, on_msg);
```

--------------------------------

### Example usage of eXosip_call_send_answer for ringing and 200 OK responses

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_call.md

Demonstrates sending a default 180 Ringing response and a custom 200 OK response with an SDP body. Requires locking the eXosip context during these operations.

```c
/* 180 Ringing, default answer */
eXosip_lock(ctx);
eXosip_call_send_answer(ctx, ev->tid, 180, NULL);   /* build+send in one call */
eXosip_unlock(ctx);

/* later: 200 OK with SDP (pattern from ht1-callcontrol.dox) */
osip_message_t *answer = NULL;
eXosip_lock(ctx);
if (eXosip_call_build_answer(ctx, ev->tid, 200, &answer) != 0) {
    eXosip_call_send_answer(ctx, ev->tid, 400, NULL);
} else {
    /* app-negotiated SDP body */
    osip_message_set_body(answer, my_sdp, strlen(my_sdp));
    osip_message_set_content_type(answer, "application/sdp");
    eXosip_call_send_answer(ctx, ev->tid, 200, answer);
}
eXosip_unlock(ctx);
```

--------------------------------

### eXosip_transport_set usage example

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_setup.md

Shows how to build a SIP message and force TCP transport using eXosip_transport_set before sending it with eXosip_message_send_request.

```c
osip_message_t *msg = NULL;
if (eXosip_message_build_request(ctx, &msg, "PING", "sip:a@b.com", "sip:me@x.com", NULL) == 0) {
    eXosip_transport_set(msg, "TCP");
    eXosip_message_send_request(ctx, msg);
}
```

--------------------------------

### eXosip_insubscription_build_notify declaration and usage

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_subscribe.md

Builds a NOTIFY within the incoming subscription, setting the Subscription-State header from the status/reason. Then send it via eXosip_insubscription_send_request. The example uses EXOSIP_SUBCRSTATE_TERMINATED with NORESOURCE reason and sets a PIDF body.

```c
int eXosip_insubscription_build_notify (struct eXosip_t *excontext, int did, int subscription_status, int subscription_reason, osip_message_t ** request);
```

```c
osip_message_t *notify = NULL;
if (eXosip_insubscription_build_notify(ctx, ev->did,
        EXOSIP_SUBCRSTATE_TERMINATED, NORESOURCE, &notify) == 0) {
    osip_message_set_body(notify, pidf_xml, strlen(pidf_xml));
    osip_message_set_content_type(notify, "application/pidf+xml");
    eXosip_insubscription_send_request(ctx, ev->did, notify);
}
```

--------------------------------

### Extract remote audio address on EXOSIP_CALL_INVITE

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_event.md

Example showing how to retrieve the remote SDP and extract the audio connection and media during an EXOSIP_CALL_INVITE event, printing the remote audio IP if available.

```c
/* on EXOSIP_CALL_INVITE: extract the remote audio address */
sdp_message_t *remote = eXosip_get_remote_sdp(ctx, ev->did);
if (remote) {
    sdp_connection_t *conn = eXosip_get_audio_connection(remote);    sdp_media_t *med = eXosip_get_audio_media(remote);    if (conn)
        printf("remote audio IP: %s\n", conn->c_addr);}
```

--------------------------------

### Send a default 200 OK OPTIONS answer

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_options.md

Example of sending a default 200 OK response to an OPTIONS request.

```c
/* quick 200 OK with default answer */
eXosip_lock(ctx);
eXosip_options_send_answer(ctx, ev->tid, 200, NULL);
eXosip_unlock(ctx);
```

--------------------------------

### Parse arbitrary message body for SDP

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_event.md

Example of parsing the SDP body from an arbitrary message using eXosip_get_sdp_info, with a comment showing how to reject with 415 if no SDP is present.

```c
/* parse an arbitrary message body */
sdp_message_t *sdp = eXosip_get_sdp_info(ev->request);
if (sdp == NULL) {
    /* no SDP, or unparsable body: reject with 415 if required by app logic */
    /* eXosip_call_send_answer(ctx, ev->tid, 415, NULL); */
}
```

--------------------------------

### OSIP_MONOTHREAD main loop with eXosip_execute

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_setup.md

Example main loop for OSIP_MONOTHREAD builds, where the application must call eXosip_execute periodically. It waits for events, executes them, runs automatic actions, and frees the event.

```c
/* OSIP_MONOTHREAD main loop */
for (;;) {
    eXosip_event_t *ev = eXosip_event_wait(ctx, 0, 1);
    eXosip_execute(ctx);
    eXosip_automatic_action(ctx);
    if (ev) { /* handle */ eXosip_event_free(ev); }
}
```

--------------------------------

### eXosip_quit usage example

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_setup.md

Example of calling eXosip_quit to perform application teardown, which blocks until the background thread exits.

```c
/* ... application teardown ... */
eXosip_quit(ctx);   /* blocks until the background thread exits */
```

--------------------------------

### eXosip_init

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_setup.md

Initializes the eXosip context with default settings and prepares internal structures. Must be called once per context before any other API.

```APIDOC
## eXosip_init

### Description
Initializes the eXosip context: resets it, initializes the osip layer, installs callbacks, allocates internal resources, and sets default configuration values. Must be called once per context before any other API.

### Method
N/A (C function)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **excontext** (struct eXosip_t *) - Required - Allocated, zeroed context.

### Request Example
```c
struct eXosip_t *ctx = eXosip_malloc();
int rc = eXosip_init(ctx);
if (rc != 0) {
    /* OSIP_NOMEM or underlying osip failure */
    fprintf(stderr, "eXosip_init failed: %d\n", rc);
    exit(1);
}
```

### Response
#### Success Response
Returns `OSIP_SUCCESS` (0) on success, or a negative `OSIP_*` error code (e.g., `OSIP_NOMEM`) on failure.

#### Response Example
```c
int rc = eXosip_init(ctx);
```
```

--------------------------------

### Apply Basic Configuration Options

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/help/doxygen/ht0-initialize.dox

Sets common configuration options such as user agent, keep-alive, DNS capabilities, and DSCP.

```c
	int val;

	eXosip_set_user_agent (ctx, "exosipdemo/0.0.0");

	val=17000;
	eXosip_set_option (ctx, EXOSIP_OPT_UDP_KEEP_ALIVE, (void*)&val);

	val=2;
	eXosip_set_option (ctx, EXOSIP_OPT_DNS_CAPABILITIES, (void*)&val);

	val=1;
	eXosip_set_option (ctx, EXOSIP_OPT_USE_RPORT, (void*)&val);

	val=26;
	eXosip_set_option (ctx, EXOSIP_OPT_SET_DSCP, (void*)&dscp_value);

	eXosip_set_option (ctx, EXOSIP_OPT_SET_IPV4_FOR_GATEWAY, "sip.antisip.com");
```

--------------------------------

### Initialize eXosip Stack

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/help/doxygen/ht0-initialize.dox

Allocates the eXosip context and initializes the stack.

```c
	ctx = eXosip_malloc();
	if (ctx==NULL)
	  return -1;

	i=eXosip_init(ctx);
	if (i!=0)
	  return -1;
```

--------------------------------

### eXosip_insubscription_remove declaration and example

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_subscribe.md

Removes the incoming subscription context. Returns OSIP_BADPARAMETER when did is negative, OSIP_NOTFOUND when unknown, or OSIP_SUCCESS. The example checks for success and prints an error if removal fails.

```c
int eXosip_insubscription_remove (struct eXosip_t *excontext, int did);
```

```c
/* subscriber gone: clean up */
if (eXosip_insubscription_remove(ctx, ev->did) != 0)
    fprintf(stderr, "cannot remove incoming subscription %d\n", ev->did);
```

--------------------------------

### Public Header Files

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/README.md

The list of installed public header files for libexosip2.

```text
eXosip.h   eX_setup.h   eX_register.h   eX_call.h   eX_options.h
eX_refer.h eX_subscribe.h  eX_publish.h  eX_message.h
```

--------------------------------

### Using eXosip_refer_build_request and eXosip_refer_send_request together

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_refer.md

Builds a REFER request for a blind transfer and sends it. The snippet shows how to set up the required parameters and how to check errors. The transfer target is placed in the Refer-To header, and the from/to specify the referrer and referee. The variable refer is reused from the build and then passed to the send function.

```c
osip_message_t *refer = NULL;
int rc = eXosip_refer_build_request(ctx, &refer,
             "<sip:carol@example.com>",            /* transfer target */
             "sip:alice@example.com",              /* from */
             "sip:bob@example.com",                /* to */
             NULL);
if (rc != 0) { fprintf(stderr, "build REFER failed: %d\n", rc); return; }
if (eXosip_refer_send_request(ctx, refer) != 0)
    fprintf(stderr, "send REFER failed\n");
```

--------------------------------

### eXosip_set_cbsip_message function signature

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_setup.md

Defines the function signature for installing a SIP message callback.

```c
int eXosip_set_cbsip_message (struct eXosip_t *excontext, CbSipCallback cbsipCallback);
```

--------------------------------

### Initialize OSIP Trace

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/help/doxygen/ht0-initialize.dox

Initializes the OSIP trace. Compile the code with -DENABLE_TRACE to enable this functionality.

```c
	#include <eXosip2/eXosip.h>

	eXosip_t *ctx;
	int i;
	int port=5060;

	TRACE_INITIALIZE (6, NULL);
```

--------------------------------

### Retrieve Refer-To Header

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/help/doxygen/ht0-initialize.dox

Example of retrieving the 'refer-to' header from a SIP message within an event.

```c
  osip_header_t *referto_head = NULL;
  i = osip_message_header_get_byname (evt->sip, "refer-to", 0, &referto_head);
  if (referto_head == NULL || referto_head->hvalue == NULL)
```

--------------------------------

### eXosip_subscribe_build_initial_request

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_subscribe.md

Builds the default initial SUBSCRIBE request. Returns various OSIP error codes or OSIP_SUCCESS.

```c
int eXosip_subscribe_build_initial_request (struct eXosip_t *excontext, osip_message_t ** subscribe, const char *to, const char *from, const char *route, const char *event, int expires);
```

--------------------------------

### Removing a registration context

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_register.md

Example showing how to remove a registration context and handle potential errors.

```c
/* application no longer needs the registration */
if (eXosip_register_remove(ctx, rid) != 0)
    fprintf(stderr, "no registration %d to remove\n", rid);
```

--------------------------------

### Function signature for eXosip_register_build_initial_register_withqvalue

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_register.md

The C function signature for building an initial registration request with a qvalue.

```c
int eXosip_register_build_initial_register_withqvalue (struct eXosip_t *excontext, const char *from, const char *proxy, const char *contact, int expires, const char *qvalue, osip_message_t ** reg);
```

--------------------------------

### Allocate and initialize an eXosip context with eXosip_malloc and eXosip_init

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_setup.md

Allocates a zeroed eXosip context with eXosip_malloc, checks for allocation failure, then initializes it with eXosip_init. On initialization failure, the context is released with eXosip_quit before exiting.

```c
struct eXosip_t *ctx = eXosip_malloc();
if (ctx == NULL) {
    fprintf(stderr, "out of memory\n");
    exit(1);
}
int rc = eXosip_init(ctx);
if (rc != 0) { eXosip_quit(ctx); exit(1); }
```

--------------------------------

### eXosip_call_build_initial_invite

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_call.md

Builds a default INVITE message for initiating a SIP call. The application then inserts the SDP body and any extension headers before sending.

```APIDOC
## eXosip_call_build_initial_invite

### Description
Builds a default INVITE message for initiating a SIP call. The application then inserts the SDP body and any extension headers before sending.

### Function Signature
```c
int eXosip_call_build_initial_invite (struct eXosip_t *excontext, osip_message_t ** invite, const char *to, const char *from, const char *route, const char *subject);
```

### Parameters
- **excontext** (struct eXosip_t *) - Required - The eXosip context.
- **invite** (osip_message_t **) - Required - Pointer to the built message.
- **to** (const char *) - Required - SIP URL of the callee.
- **from** (const char *) - Required - SIP URL of the caller.
- **route** (const char *) - Optional - Route header for the INVITE. Default is NULL.
- **subject** (const char *) - Required - Subject header for the call.

### Return Value
Returns 0 on success, or an OSIP error code on failure.

### Notes
This method cannot be called unless the previous INVITE transaction is over.
```

--------------------------------

### Validate Incoming INVITE with Replaces Header

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_call.md

Example usage of eXosip_call_find_by_replaces to identify a target call for merging or continuation.

```c
/* validate an incoming INVITE claiming to replace call X */
int target = eXosip_call_find_by_replaces(ctx, refer_to_body);
if (target > 0) { /* merge/continue that call */ }
```

--------------------------------

### Initiate a SIP registration

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/help/doxygen/ht2-registration.dox

Builds an initial REGISTER request and sends it using the eXosip context. The returned registration identifier (rid) is required for future updates.

```c
  osip_message_t *reg = NULL;
  int rid;
  int i;

  eXosip_lock (ctx);
  rid = eXosip_register_build_initial_register (ctx, "sip:me@sip.antisip.com", "sip.antisip.com", NULL, 1800, &reg);
  if (rid < 0)
    {
      eXosip_unlock (ctx);
      return -1;
    }

  osip_message_set_supported (reg, "100rel");
  osip_message_set_supported (reg, "path");

  i = eXosip_register_send_register (ctx, rid, reg);
  eXosip_unlock (ctx);
  return i;
```

--------------------------------

### Send PRACK for a provisional response

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_call.md

Example of building and sending a PRACK message inside a 1xx-with-RSeq event handler.

```c
/* inside the 1xx-with-RSeq event handler */
osip_message_t *prack = NULL;
if (eXosip_call_build_prack(ctx, ev->tid, &prack) == 0)
    eXosip_call_send_prack(ctx, ev->tid, prack);
```

--------------------------------

### Sending a SIP request with eXosip_message_send_request

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_message.md

Example usage of eXosip_message_send_request to send a message and handle the returned transaction ID.

```c
int tid = eXosip_message_send_request(ctx, msg);
if (tid > 0)
    printf("MESSAGE sent, tid=%d\n", tid);
else
    fprintf(stderr, "send failed: %d\n", tid);
/* the final 2xx/4xx arrives as an EXOSIP_MESSAGE_* event carrying this tid */
```

--------------------------------

### Terminate a call from the event loop

Source: https://github.com/distrotech/libexosip2/blob/distrotech-libeXosip2/_autodocs/api-reference/eX_call.md

Example of terminating a call by locking the context, calling eXosip_call_terminate, and handling potential errors.

```c
/* hang up the call from the event loop */
eXosip_lock(ctx);
int rc = eXosip_call_terminate(ctx, ev->cid, ev->did);
if (rc != 0) fprintf(stderr, "terminate failed: %d\n", rc);
eXosip_unlock(ctx);
```