# &adminguide;

## Overview

This module provides a way to identify calls using an increasing sequence of integers.

It starts assigning an integer to a call. Next call gets next free integer in a ring. When a call finishes its assigned number shall be freed.

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- none.

### External Libraries or Applications

The following libraries or applications must be installed before running &kamailio; with this module loaded:

- None.

## Parameters

### `start` (integer)

First number to assign when no number has been assigned yet.

This parameter has no default value. Not setting it raises an error.

Its value shall be greater than zero.

#### Set `start` parameter

    ...
    modparam("call_obj", "start", 10)
    ...

### `end` (integer)

Last number to assign when all other numbers have been already assigned.

No default value. Not setting this parameter raises an error.

Its value shall be greater than zero.

#### Set `end` parameter

    ...
    modparam("call_obj", "end", 93)
    ...

## Functions

### `call_obj_get(reply_number)`

Get next free number. reply_number parameter is a variable where function will store result in string format.

#### `call_obj_get` usage

    ...
    if (call_obj_get("$dlg_var(x)")) {
    	xlog("Object: $dlg_var(x)\n");
    }
    ...

### `call_obj_free(object_number)`

Mark an object_number as free, so it can be assigned again. This number will not be readily assigned until a loop in the ring has completed. object_number shall be provided in string format.

#### `call_obj_free` usage

    ...
    $dlg_var(y) = "27";
    if (call_obj_free("$dlg_var(y)")) {
    	xlog("object $dlg_var(y) freed OK\n");
    }
    ...

## RPC Commands

### `call_obj.free`

Free an object.

Parameter is a number represented in string format.

Name: call_obj.free

Parameters: object_number

#### `call_obj.free` usage

    ...
    &sercmd; call_obj.free s:12
    ...

### `call_obj.stats`

Return some statistics about call_obj module.

It currently returns:

- Start: Number of first object

- End: Number of last object in range

- Total: Total assignable objects

- Assigned: Number of currently assigned objects

Name: call_obj.stats

Parameters: none

#### `call_obj.stats` usage

    ...
    &sercmd; call_obj.stats
    ...

### `call_obj.free_all`

Make all objects free at once.

Name: call_obj.free_all

Parameters: none

#### `call_obj.free_all` usage

    ...
    &sercmd; call_obj.free_all
    ...

### `call_obj.list`

List all active calls which duration is longer than a value in seconds.

Name: call_obj.list

Parameters: duration limit

limit parameter is optional

#### `call_obj.list` usage

    ...
    Show every call which duration is less than or equal to 24 seconds:
    &sercmd; call_obj.list 24

    Same but limit output to at most 5 calls:
    &sercmd; call_obj.list 24  5

    Same but show again all calls (0 means no limit):
    &sercmd; call_obj.list 24  0
    ...