Additions to the Client/Server API to support Queues and other things GetFirstOnQueue(void) This method returns the following notification: QUEUE_ENTRY HPARTY hParty; // the hParty of the first queue entry long QueueID; // which subqueue this entry is waiting for short position; // the number of entries ahead of this one // within the specific subqueue. Note that this method takes no argument, and is probably handled by Mike. If there are no entries on the queue, you will receive a QUEUE_ENTRY notification with an hParty of zero (0). GetNextOnQueue(HPARTY hPartyThisOne) This method returns a QUEUE_ENTRY notification (see above) for the next entry on the master queue. If you have reached the end of the queue, you will receive a QUEUE_ENTRY notification with an hParty of zero (0). If hPartyThisOne refers to a party that is no longer on the master queue, then GetNextOnQueue() behaves like GetFirstOnQueue() and you will receive the hParty of the head of the queue. Thus, you may end up iterating over parties more than once. GetPartyQueueStatus(HPARTY hParty) This method returns a QUEUE_ENTRY notification for the given hParty. It can be used to poll for a current position on the specific subqueue, or to find out which subqueue a specific party is on. RemovePartyFromQueue(HPARTY hParty) This method removes the given hParty from any queues that it might be waiting on. If the hParty is not actually on a queue, this is benign. However, you should not call RemovePartyFromQueue() on a party which you don't own (see AcceptCall). If you wish to grab a call out of a queue, first use AcceptCall() to assert your interest in owning it; if AcceptCall() succeeds, then you may call RemovePartyFromQueue() and set its state to Active. RemovePartyFromQueue returns the following notification: QUEUE_DELETION HPARTY hParty; // the party that has been removed long QueueID; // the subqueue that has been depleted short position; // the position that the party held The same notification is sent as an unsolicited notification whenever a party is removed from a queue. The signature of this notification is the same as that for QUEUE_ENTRY. AddPartyToQueue(HPARTY hParty, long QueueID, short position) This method adds the given party to the given queue, such that no more than *position* other parties precede it on the specific subqueue. See the definition of the NealPartyObject::AddToQueue method for details on how this works. This method returns the following notification: QUEUE_ADDITION HPARTY hParty; long QueueID; short position; It is also send as an unsolicited notification whenever a party is added to a queue. This signature of this notification is the same as that for QUEUE_ENTRY. RepositionPartyOnQueue(HPARTY hParty, long QueueID, short position) This method moves the given party within the given queue, such that no more than *position* other parties precede it on the specific subqueue. See the definition of the NealPartyObject::AddToQueue method for details on how this works. This method returns the following notification: QUEUE_REPOSITION HPARTY hParty; long QueueID; short oldposition; short newposition; It is also send as an unsolicited notification whenever a party is repositioned within a queue. In addition, we will add the following more general mechanism for the Client and Server to exchange information about parties: SetPartyField(HPARTY hParty, short index, long newvalue) SetPartyStringField(HPARTY hParty, short index, string newvalue) GetPartyField(HPARTY hParty, short index) These methods will be used to expose party-specific functionality to the client. The specifics of what indeces map to what fields will be determined as we progress. Each of these methods will result in one of the following notifications: PARTY_FIELD HPARTY hParty; short index; long value; PARTY_STRING_FIELD HPARTY hParty; short index; string value; TransferToExtension(HPARTY hParty, string Extension, short flags) TransferToTrunkDial(HPARTY hParty, string DialString, short flags) These functions are similar to CallAddExtension and CallAddTrunkDial, except that they mark the action as a transfer. The new party, given by Extension or by DialString, will take the role of hParty in the call. The "flags" argument is used to specify the kind of transfer: 0 -- client-driven transfer. The method works exactly like the corresponding "CallAdd..." method, except that the appropriate "bookkeeping fields" are updated to remember that this was a transfer. 2 -- blind transfer. The server will do all the dirty work; the given hParty will go disconnected, etc. 3 -- blind transfer with recall. The server will do all the dirty work, but the given hParty only goes to on hold -- if the transfer fails, the call is reconnected to hParty. 4 -- supervised transfer. The server will do all the dirty work. There are no new notifications here. You will see a PARTY_ADDED notification as well as whatever other notifications are appropriate. There is a new notification which will be broadcast to all clients whenever the server is shutting down. SERVER_SHUTDOWN short SecondsToLive; string MessageToDisplay; Similarly, whenever a thread needs to be restarted, all clients will be notified: SERVER_THREAD_RESTARTED short DeviceID; QueryServerStatus() There will be a new method that a client can use to query information about the server's status. For example, if we are running in crippled mode, the client may wish to display a warning. This method can be called at any time, but is primarily intended for use at startup; we'll probably send out unsolicited versions of the SERVER_STATUS notification whenever things change. SERVER_STATUS short enumServerStatus; long flags; It's up to Mike how to define these. I assume that there will be a bitmapped set of flags, indicating which components are working: Kernel, Database, Scheduler, etc. There is a new notification which will be broadcast to all clients whenever a device's state changes. This is more specific than TUI_STATUS, which will tell you which area of the actor a device is in. The two notifications complement one another. DEVICE_HOOKSTATE short deviceid; short status; long BestGuessPBEID; This notification can be used to update "line monitor" displays, such as the transfer-target dialog or any sort of "blinking lights" interface. The "BestGuessPBEID" is the device's most-likely PBEID. The values for status are: 0 - onhook, DND off. 1 - onhook, DND on. 2 - onhook, at least one call on hold, DND off. 3 - onhook, at least one call on hold, DND on. 4 - onhook, ringing, DND off. 5 - onhook, ringing, DND on. (Can this happen?) 6 - onhook, ringing, at least on call on hold, DND off. 7 - onhook, ringing, at least on call on hold, DND on. 8 - offhook, active call, DND off. 9 - offhook, active call, DND on. 10 - offhook, active call and another in call-waiting, DND off. 11 - offhook, active call and another in call-waiting, DND on. 12 - offhook, in the TUI, no calls on hold, DND off. 13 - offhook, in the TUI, no calls on hold, DND on. 14 - offhook, in the TUI, at least one call on hold, DND off. 15 - offhook, in the TUI, at least one call on hold, DND on. As you can figure out, these values are bitmapped: 1 = DND on 2 = Device owns a call that is not currently active 4 = Device is using the TUI 8 = Offhook Certain notifications and methods were supposed to be added or modified under API 4. Let's make sure they are correct under API 5: PARTY_STATUS_EX (third argument is a short DeviceID, not string). UI_SUPPORT_STARTED (should have three arguments: HCALL, HPARTY, long, just like CALL_STARTED). TELEPHONY_ERROR (should bae five arguments: HPARTY, short, short, long, long.) Certain methods were proposed in API 4 for recording ongoing calls. They should be replaced with the following methods: CallAddRecordingParty(HPARTY hPartyResponsible) This method adds a special "recording party" to the call. It is similar to CallAddExtension. You will receive a PARTY_ADDED notification for the recorder. Recording will not begin immediately, however. You will control that via: RecordingPartyStart(HPARTY hRecordingParty) RecordingPartyPause(HPARTY hRecordingParty) RecordingPartyClose(HPARTY hRecordingParty) RecordingPartyCancel(HPARTY hRecordingParty) These methods will send back the following notifications: RECPARTY_STARTED HPARTY hParty; RECPARTY_INTERRUPTED HPARTY hParty; long msPos; RECPARTY_DONE HPARTY hParty; long AudioClipID; RECPARTY_CANCELLED HPARTY hParty; There is only one clip-buffer for recording parties.