The ASTi conference calling architecture provides a means for call endpoints (operators) to coordinate private intercom channels for communication. Unlike traditional telephone models, a call is not a connection between two endpoints, rather it is a rendezvous point for multiple endpoints. Hence, a point-to-point call is defined as a conference call with exactly two members.
Note that the call system works only between servers in the installed scenario.
Calling may not be enabled for all software clients. It is disabled by default on a per-Role basis. Use Role_CallingEnabled to check if a certain Role configuration has calling enabled.
The following sections will describe in detail the core concepts necessary to use the call system APIs outlined in this documentation.
Operators are defined as the set of peers visible to a given client within an installed scenario. Each operator has a unique ID which is used to perform actions on that operator. The list of available operator IDs are accessible using the Operator_IDFirst and Operator_IDNext functions.
Operators also have a set of string fields associated with them that carry information such as name, connection status and call system activity (see Operator_GetField).
For the purposes of accessing call information, Operators are referred to interchangeably as Endpoints. For example, an Operator unique ID is used as the Endpoint ID when sending a call invitation (see Invitations).
A version counter increments whenever operator information is updated (see Operator_Version).
Calls are defined as private intercom channels that multiple operators can join to communicate. Each call has a unique ID that is generated when it is initially created (see Call_Create).
The call itself does not have any state information. Rather, each endpoint that has knowledge of the call advertises it's current state with respect to the call, which may be signaling, connected, leaving or holding (see Call_Progress). An endpoint invited to a call will begin communicating on the call only after updating it's progress to the connected state.
A call will be automatically destroyed when the second-to-last endpoint leaves the call (see Call_Leave). For a two-member call, this will occur when one of the members leaves the call. In this case, the call ID will no longer appear in the call list accessible using the Call_IDFirst and Call_IDNext set of functions.
Calls are private, and therefore can only be accessed through creation or invitation. An endpoint with knowledge of a call ID is able to view the list of other endpoints associated with the call along with their state (see Call_Endpoint_State).
Additionally, each operator advertises a 'callactive' field (see Operator_GetField) which indicated whether they are currently connected to a call. This information can be used to display a busy state to all other operators.
A version counter increments whenever call or endpoint information is updated (see Call_Endpoint_Version).
Any endpoint with knowledge of a call ID (through creation or invitation) can invite other operators to join that call. An invitation consists of a unique ID for a call and the unique ID for the endpoint that sent the invitation. Information about the endpoint can be accessed using the Operator_GetField function using the endpoint ID.
Unlike traditional telephone dialing, invitations do not have state or ownership. Instead, invitations are more analogous to emails in that they are sent from sender to recipient once and cannot be retracted.
Invitations can be accepted, declined or ignored. To accept a call, use the Call_Progress function to update the call state to 'connected'. To decline a call, use the Call_Leave function. Note that once invited, an endpoint will implicitly join a call as signaling to indicate that it has been invited, therefore it is necessary to explicitly leave the call when declining. The signaling state can be used to display endpoints that have been invited, but not yet accepted or declined, an invitation.
Invitations can be accessed using the Call_Invitation_First and Call_Invitation_Next functions. Note that they will persist until they are explicitly cleared using the Call_Invitation_ClearAll function. A version counter increments whenever a new invitation is received (see Call_Invitation_Version).
If a call is destroyed and no longer accessible using the Call_IDFirst and Call_IDNext set of functions, then any invitations for that call are invalid and should be discarded.
A phone is defined as an audio device that can be associated with a call. It also has an individual volume control (see Phone_SetVolume). An operator/endpoint can join multiple calls, but they require a phone to transmit and receive audio with other endpoints on the call.
Phone_ListCount will indicate whether the current operator has a phone assigned (currently a one phone maximum). A call can be assigned to the phone using the Phone_SetCall function and the current call ID is available using the Phone_CallActive function.