Call Ownership

The mechanism with which applications control calls is based on the concept of ownership. At any given time, one or more applications can own a call. While an application has ownership of a call, it is allowed to manipulate the call in ways that affect the state of the call. An application that does not own a call (but has a handle to it) is a monitor of the call and is prevented from manipulating it. It can only perform status- and information-query operations on that call. While one or more applications are owners of a call, still other applications can be monitoring the call.

Ownership of a call is assigned to applications according to the following rules:

• An application that makes an outgoing call is the initial sole owner of that call. Other applications monitoring the line will be informed of the outgoing call at the time the first LINE_CALLSTATE message is received. Usually, this notification occurs when a dial tone is initially detected.
• Ownership of an incoming call is assigned to one application only. This assignment avoids the situation in which, depending on timing, different applications may seize control at different times, causing unpredictable results.
• An application that is currently an owner of a call can pass ("hand off") ownership to another application that has the call's line open. While handing off ownership of a call, the original owner application can specify the new media type of the call. When the handoff succeeds, the original application remains an owner of the call, and it can then choose to either deallocate its handle (if it is no longer interested in the call), change to being a monitor (using lineSetCallPrivilege), or remain an owner (although doing so is discouraged). The original application's privilege is not automatically changed by lineHandoff. For more information on the two types of call handoffs (directed and media-mode), see Directed Handoffs and Media Mode Handoffs.
• If a target application for the handoff is found, and if it is already a co-owner of the call, it will see no effect caused by the handoff, although it will receive a LINE_CALLSTATE message. This message repeats the fact that it is an owner to alert it that another application has explicitly asked it to take control of the call. The application initiating the handoff is informed about the success of the handoff.
• If there is no target application for the requested handoff and the call is active, an error is returned. No handoff takes place.
• Handing off a call between applications never affects the state of the physical call as perceived by the switch or the service provider.
• An application that does not have (but wants) ownership of a call may request ownership. The application can select calls based on a number of criteria, ranging from all calls on a particular line or address (a phone number assigned to the line, using lineGetNewCalls), to calls related to a specified call (using lineGetConfRelatedCalls). An application that calls lineGetNewCalls or lineGetConfRelatedCalls will always receive a monitor handle. If it wants to become an owner of a call it receives, it must then call lineSetCallPrivilege. If it determines that it is not interested in one or more of the calls to which it receives handles using lineGetNewCalls or lineGetConfRelatedCalls, it must call lineDeallocateCall for each such handle to release the internal resources maintained to track the call ownership.
• Any application that asks for ownership receives it; any application that is offered ownership cannot refuse it. An application that becomes an owner through a handoff actually becomes a co-owner of the call. When the call is initially presented by the provider, the initial owner is the sole owner of the call.
• The originally owning applications are informed about the existence of every new owner. Monitoring applications are informed as well.

Note  Co-owned calls (calls simultaneously owned by more than one application), no protection is offered to prevent the applications from interfering with each other. For this reason, maintaining ownership after a handoff or after ownership is taken by another application is discouraged.

Because media streams are not managed by the Telephony API, call handoff does not handle the handoff of the call's media stream. Media-stream handoff must be carried out using commands from an appropriate media-control API or directly coordinated between the applications involved.