# Functions

## `tcp_conid_alive(conid)`

Check the state of a TCP or WS connection ID

Meaning of the parameters is as follows:

- conid (optional): the Kamailio internal connection id (as in the $conid pseudovariable).

Return values:

1: Connection is OK

-1: Connection has errors, does not exist or is about to be closed)

### `tcp_conid_alive` usage

    ...
    	$var(conid) = $conid;
    	if(!tcp_conid_alive("$var(conid)")) {
    		xlog("L_ERR", "Connection $conid can no longer be used\n");
    	}
    ...

## `tcp_conid_state(conid)`

Check the state of a TCP or WS connection ID

Meaning of the parameters is as follows:

- conid (optional): the Kamailio internal connection id (as in the $conid pseudovariable).

Return values:

1: Connection is OK

2: Socket is accepting incoming connections

3: Socket is setting up outgoing connection

-1: Connection does not exist (or was closed)

-2: Socket has reached EOF

-3: Socket error has occurred. Connection will likely close.

-4: Socket is in unknown bad state. Connection will likely close.

### `tcp_conid_state` usage

    ...
    	if(!tcp_conid_state("$var(conid)")) {
    		xlog("L_ERR", "Connection $conid is closed or malfunctional\n");
    	}
    ...

## `tcp_keepalive_enable([conid], idle, count, interval)`

Enables keepalive on a TCP connection.

Meaning of the parameters is as follows:

- conid (optional): the &kamailio; internal connection id on which TCP keepalive will be enabled. If no parameter is given, the keepalive mechanism will be enabled on the current message source connection.

- idle (seconds): the time before the first keepalive packet is sent out.

- count: number of non-acked keepalive before resetting the connection.

- interval (seconds): time between two keepalive probes.

Returns 1 on success, -1 on failure.

### `tcp_keepalive_enable` usage

    request_route {
    	if (is_method("INVITE")) {
    		$avp(caller_conid) = $conid;
    		t_on_reply("foo");
    	}
    	...
    }

    onreply_route[foo] {
    	if (is_method("INVITE") && status == 200) {
    		# enable on callee's connection
    		tcp_keepalive_enable("60", "5", "5");
    		# enable on caller's connection
    		tcp_keepalive_enable("$avp(caller_conid)", "60", "5", "2");
    	}
    	...
    }

## `tcp_keepalive_disable([conid])`

Disables keepalive on a TCP connection.

Meaning of the parameters is as follows:

- conid (optional): the &kamailio; internal connection id on which TCP keepalive will be disabled. If no parameter is given, the keepalive mechanism will be disabled on the current message source connection.

Returns 1 on success, -1 on failure.

### `tcp_keepalive_disable` usage

    request_route {
    	...
    	if (is_method("BYE")) {
    		$avp(bye_conid) = $conid;
    		t_on_reply("foo");
    	}
    	...
    }

    onreply_route[foo] {
    	...
    	if (is_method("BYE") && status == 200) {
    		tcp_keepalive_disable();
    		tcp_keepalive_disable("$avp(bye_conid)");
    	}
    	...
    }

## `tcp_set_connection_lifetime([conid], lifetime)`

Sets the connection lifetime of a connection (TCP).

Meaning of the parameters is as follows:

- conid (optional): the &kamailio; internal connection id on which to set the new lifetime. If no parameter is given, it will be set on the current message source connection.

- lifetime (seconds): the new connection lifetime.

Returns 1 on success, -1 on failure.

### `tcp_set_connection_lifetime` usage

    ...
    # use 10s as default lifetime
    tcp_connection_lifetime=10
    ...

    request_route {
            ...
            if (is_method("REGISTER") && pv_www_authenticate("$td", "xxx", "0")) {
                    # raise the TCP lifetime to a bigger value
                    tcp_set_connection_lifetime("3605");
            }
            ...
    }

## `tcp_enable_closed_event([conid])`

Explicitly enables the "tcp:closed" event route on a TCP connection.

Meaning of the parameters is as follows:

- conid (optional): the &kamailio; internal connection id. If no parameter is given, it will be enabled on the current message source connection.

Returns 1 on success, -1 on failure.

### `tcp_set_closed_event` usage

    ...
    # "tcp:closed" event route is "manual" mode
    modparam("tcpops", "closed_event", 2)
    ...

    request_route {
    	...
    	if (is_method("REGISTER") && pv_www_authenticate("$td", "xxx", "0")) {
    		# it will be called for this specific connection
    		tcp_enable_closed_event();
    	}
    	...

    }

    event_route[tcp:closed] {
    	xlog("connection $conid was closed");
    }

## `tcp_get_conid(hostport, pvname)`

Get the connection id based on target host:port. The connection id is set in the variable named by pvname parameter.

Meaning of the parameters is as follows:

- hostport - target "host:port" address, the port can be omitted (default to 5060) and the parameter can contain variables.

- pvname - target variable name.

Return values:

1: connection was found

-1: connection was not found or an error occurred

### `tcp_get_conid` usage

    ...
    	if(tcp_get_conid("127.0.0.1:5060", "$var(conid)")) {
    		xlog("connection id is: $var(conid)\n");
    	}
    ...