The Agent Reservation feature provides a way to resolve race conditions between several T-Server clients attempting to access the same agent. T-Server collects concurrent reservation requests during a configurable time interval (set with the T-Server request-collection-time option). Once this collection time expires, T-Server randomly chooses one of the highest priority requests, positively responds to it with EventAgentReserved, and fails the rest of requests, rejecting each with EventError.
The successful agent reservation record remains active for some duration of time (the function's duration parameter). Setting duration to 0 cancels the reservation record. An attempt to cancel a non-existing reservation generates EventError. Setting the duration to -1 forces T-Server to use a preconfigured duration. (See the reservation-time T-Server option.)
Any subsequent attempt to reserve an already-reserved agent fails and results in the generation of EventError. There is an exception, however, if the reject-subsequent-request option is set to false. In this case, the T-Server's client whose reservation request succeeded has the ability to reset the length of duration for an agent that is already reserved.
The agent being reserved can be defined by agent_dn, agent_id, or agent_place—at least one of these parameters must be present in the request. If more than one of these parameters is specified in the request, the reservation occurs on all specified entities.
The Agent Reservation feature does not prevent the reserved agent from changing state, receiving direct calls or calls distributed from ACD Queues. This feature is only intended as a way of synchronizing the operation of several T-Server clients. The agent is temporarily reserved for exclusive use, and other potential clients must either wait for the reservation to end, or choose an alternative agent.
|server||Local server handle to T-Server in question.|
|agent_dn||DN number to be reserved (may be NULL).|
|agent_id||Agent to be reserved (may be NULL).|
|agent_place||Place to be reserved (may be NULL).|
|duration||Required reservation time, in milliseconds. Specify -1 to use default of 100000 milliseconds. The default value is set by the reservation-time configuration option.|
|priority||Request priority. Specify -1 to use default of 0, the lowest priority value.|
|reasons||A pointer to a data structure that provides additional information associated with this action.|
|extensions||A pointer to an additional data structure.|
Standard (See standard-return-values.)