                    README - AT&T private data support
                                     
This file contains supplemental information on the support of private data
extensions in the AT&T Definity G3 PBX Driver.



To the end-user/installer:

This diskette includes run-time libraries, ATTPRIV.DLL (for Windows 3.1)
and ATTPRIV.NLM (for NetWare), needed by some applications which
communicate with AT&T Definity G3 PBXs.  Copy:

     ATTPRIV.DLL to the same directory as CSTA.DLL
and
     ATTPRIV.NLM to the same directory as TSLIB.NLM

to ensure that those applications have access to AT&T private data
extensions.



To the application software developer:

Also included on this diskette are the additional software components
needed to develop applications which use the AT&T private data extensions:

  ATTPRIV.H - header file containing AT&T private data definitions and
  function prototypes
  
  ATTPRIV.LIB - import library for linking Windows 3.1 applications to
  ATTPRIV.DLL
  


                          Using CSTA Private Data
                                     
The private data feature of the CSTA Client Library provides a way for
applications and PBX drivers to exchange data not defined by the ECMA
standard.  By mutual agreement, any sequence of bytes may be transmitted,
in either direction.  The Client Library and the Telephony Server do not
place any interpretation on this data; representation issues such as byte
order and structure alignment are the joint responsibility of the PBX
driver and the application.

The private data feature is accessed through the PrivateData_t structure
defined in acs.h:

   typedef struct PrivateData_t {
       char         vendor[32];
       unsigned short length;
       char         data[1];    // actual size determined by app
   } PrivateData_t;

The vendor string is defined by each PBX driver, as a means of
distinguishing one vendor's encoding from another's.

The length field specifies the number of bytes contained in the data array.
Although the data array  is declared to contain a single byte, this does
not imply an actual size; this structure is intended as a template for a
buffer of sufficient size to contain the data.  Some sample code fragments:

Example 1:

   char buffer[32+2+100];        /* vendor + length + data */
   PrivateData_t *priv;
   struct xxx mystruct;          /* PBX driver-defined */
   
   priv = (PrivateData_t *)buffer;
   
   /* populate "mystruct" here ... */
   
   strcpy (priv->vendor, "Acme PBX Inc."); /* sender fills in */
   priv->length = sizeof(mystruct);
   memcpy (priv->data, &mystruct, sizeof(mystruct));


Example 2:

   struct {
       PrivateData_t hdr;
       char buffer[99];         /* data + buffer = 100 bytes */
   } myPriv;
   struct xxx *mystruct;         /* PBX driver-defined */
   
   mystruct = (struct xxx *)&myPriv.hdr.data;   /* point into data */
   
   /* populate "mystruct" here ... */
   
   strcpy (myPriv.hdr.vendor, "Switches 'R' Us");
   myPriv.hdr.length = sizeof(mystruct);


In each of the above cases, there is room in the data array for up to 100
bytes of PBX driver-defined data.  When transmitting private data, the
length field should be set to the actual size of the data; when receiving
private data, the length field should be set to the maximum size of the
buffer.

                        AT&T Private Data Encoding
                                     
The AT&T Definity G3 PBX Driver has defined a simple tag/length/value (TLV)
encoding for its private data; other PBX driver vendors are free to define
their own standards.  For AT&T private data, the following layout is
applied to the data part of the PrivateData_t structure:

     data member of PrivateData_t partitioned into N tagged items

                |<- 1st item->|   |<- 2nd item->|   |<- 3rd item->|
     _______________________________________________________________
    |   |   |   |   |         |   |   |         |   |   |         |
    |enc| N |tag|len|  value  |tag|len|  value  |tag|len|  value  | ...
    |___|___|___|___|_________|___|___|_________|___|___|_________|_
    | 2 | 2 | 2 |    len*     | 2 |    len*     | 2 |    len*     |


     (*) value is padded to even boundary

Integer values are stored in native Intel ("little-endian") byte order.  The
enc field contains a constant which may be used in the future to distinguish
other encoding methods.  The N field indicates the number of tagged items
present.  The same tag may appear more than once.  The tags and corresponding
data structures are defined in attpriv.h.

To facilitate application coding when using AT&T Definity G3 private data,
a set of access routines are provided as a standalone library, attpriv.  It
is not necessary to understand the details of the TLV encoding; the library
routines take care of this.  The application is responsible, however, for
allocating sufficient space for the private data.

The following routines are provided:

    initATTPrivate(priv) - initializes the PrivateData_t structure prior
     to adding data (used by sender)
     
    addATTPrivate(tag, data, priv) - appends a tagged data item to the
     PrivateData_t structure (used by sender)
     
    getATTPrivate(tag, priv, N) - retrieves the Nth occurrence (starting
     from 0) of a tagged data item from the PrivateData_t structure (used
     by receiver)
     
To receive private data in an event, it is first necessary to allocate a
PrivateData_t structure with sufficient data buffer space, and initialize
the length field.  Since it is modified upon return,  the length field must
be initialized before each call to acsGetEventPoll().  The address of this
structure is then passed to acsGetEventPoll():

   privData.length = MAX_PRIVATE_DATA;     /* needs to be defined */
   acsGetEventPoll (acsHandle, &eventBuf, &eventBufSize, &privData,
   &numEvents);


On successful return from acsGetEventPoll(), if the returned event is
expected to contain private data, use getATTPrivate() to retrieve it:

   UserEnteredCode_t *uec;  /* get collected digits */
                            /* defined in attpriv.h */
   
   /* find the first (0th) occurrence of ATT_PRIV_UEC data type */
   
   uec = (UserEnteredCode_t *)getATTPrivate (ATT_PRIV_UEC, &privData, 0);
   
   if (uec != NULL)
   {
      strcpy (digits, uec->data);    /* save the digits, etc. */
   }
   
   /* else, no UEC private data,  just continue */


The getATTPrivate() function returns a pointer to the requested data item,
or NULL if it is not present.  Where possible, getATTPrivate() will perform
any necessary conversions to native byte order (for non-Intel platforms).

To send private data in a request, allocate a PrivateData_t structure with
sufficient data buffer space, and initialize it with initATTPrivate(),
followed by one or more calls to addATTPrivate().  The address of this
structure is then passed in the API call:

   initATTPrivate (&privData);   /* initializes vendor and length */
   
   uec.size = sizeof(uec);/* every item begins with size field */
   /* populate rest of structure here ... */
   
   addATTPrivate (ATT_PRIV_UEC, (void *)&uec, &privData);
   /* additional items may be added here ... */
   
   /* send data along with MakeCall or whatever ... */
   cstaMakeCall (acsHandle, invokeID, calling, called, &privData);
                                     
                                     
                       AT&T Private Data Description
                                     
User Entered Code (UEC) is the only private data that is supported by the
AT&T DEFINITY G3 PBX Driver Release 1.1. More private data will be
supported in future releases.  This section describes the UEC.



User Entered Code Description

User Entered Code is touch-tone digits that are entered by a Call Prompting
user via the collect digits command from a Call Vectoring step (for more
information regarding Call Prompting feature see the Call Vectoring/Expert
Agent Selection (EAS) Guide 555-230-520).  This command allows the G3
switch to collect up to 24 digits (G3V3) (16 digits on earlier versions of
G3) from a touch-tone phone.

A UEC is reported to a client application in a Delivered Event Report (see
the Definity System Programmer's Guide for detailed information on the
Delivered Event) in the following structure:

     typedef struct UserEnteredCode_t
     {
          UINT16    size;               // sizeof(UserEnteredCode_t)
          UINT8     type;                    // type of user code
     #define   UE_ANY              '\x00
     #define   UE_LOGIN_DIGITS          '\x02'
     #define   UE_CALL_PROMPTER         '\x05'
     #define   UE_DATA_BASE_PROVIDED    '\x11'
     #define   UE_TONE_DETECTOR         '\x20'
          UINT8     timeout;            // timeout interval 0-63 (not used)
          UINT8     indicator;               // collect/collected
indication
     #define   UE_COLLECT     '\x00'    // digits to be collected
     #define   UE_ENTERED     '\x01'    // user entered digits
          char data[MAX_USER_CODE+1];   // NULL terminated string of digits
          char collectVDN[MAX_VDN+1];   // NULL terminated string of digits
     } UserEnteredCode_t;

The timeout field is not used in Release 1.1.  The indicator field is
always set to UE_ENTERED. The data field contains the User Entered Digits.
The collectVDN field contains the VDN that reports the UEC, not the one
that actually collects the digits.  The collectVDN field is used to
identify the VDN that reports the UEC.



How to Collect UEC

The following are procedures for setting up simple vector steps and CSTA
Monitor Service requests that are required for a client application to
receive UECs from the switch.  To enable the G3PD to capture UECs, each VDN
which is to report a UEC must be monitored by a client application using
the cstaMonitorCallsViaDevice( ) service.  Normally, monitor filtering
should be selected to suppress client event reports for the VDN.

1. On the G3 switch, administer a VDN and a vector using the Call Prompting
feature to collect digits.

  The vector should include a "collect digits" command and a "route"
  command.  The number of digits requested from the caller must be
  specified.  The purpose of this VDN is to collect UEC; it will not
  report the UEC to the G3PD, even if it is monitored.  The route command
  must redirect the call to a second VDN.  The first VDN doesn't have to
  be monitored by any client application.
  
2. Administer a second VDN and vector to receive calls redirected from the
first VDN.

  The purpose of this VDN is to report the UEC to the G3PD. Thus, the G3PD
  must be instructed to monitor this VDN.  Use the
  cstaMonitorCallsViaDevice( ) service, with appropriate filtering.  This
  VDN should  redirect the call to its destination.  The destination can
  be a station extension, an ACD split, or another VDN.
  
3. If the destination is a station extension and the station is monitored
by a client using the cstaMonitorDevice( ) service, the client will receive
the UEC (collected by the first VDN) in a Delivered Event Report.

4. If the destination is an ACD split and an agent station in the split is
monitored by a client using the cstaMonitorDevice( ) service, the client
will receive the UEC (collected by the first VDN) in a Delivered Event
Report.

5. If the destination is a VDN and if the VDN is monitored by a client
using the cstaMonitorCallsViaDevice( ) service, the client monitoring the
VDN will NOT receive the UEC collected by the first VDN.

6. UEC is reported in Delivered Event Reports (for detailed information see
following Call Scenarios).  If multiple UECs are collected by multiple VDNs
in call processing, only the most recently collected UEC is reported.



Limitations

1. A monitored VDN only reports the UEC it receives from a VDN that routes
to it.  It will not report UEC it collects or UEC collected after the call
is redirected from the VDN.

2. A monitored station reports only the UEC that is received by the VDN
that redirects the call to the station, provided that the VDN is monitored
(see Call Scenario 2).



Call Scenario 1

VDN 24101 is mapped to vector 1 and vector 1 has the following steps:

     1. collect 16 digits after announcement extension 1000

     2. route to 24102

     3. stop

VDN 24102 is mapped to vector 2 and vector 2 has the following steps:

     1. route to 24103

     2. stop

where 24103 is a station extension.

When a call arrives on VDN 24101, the caller hears the announcement and the
switch waits for the caller to enter 16 digits.  After the 16 digits are
collected in time (if the collect digits step times out, next step is
executed), the call is routed to VDN 24102. The VDN 24102 routes the call
to station 24103.

VDN 24101 does not need to be monitored; the collected digits will NOT be
reported in the Delivered Event Report (Call Delivered to an ACD Device)
sent to a client monitoring VDN 24101.  This is because the Delivered Event
Report is sent before the digits are collected.

If VDN 24102 is monitored by the cstaMonitorCallsViaDevice( ) service, the
16 digits collected by VDN 24101 will be reported in the Delivered Event
Report (Call Delivered to an ACD Device) sent to the client monitoring VDN
24102 when the call is routed to the VDN.  Monitoring VDN 24101 is not
required for the client monitoring VDN 24102 to receive the UEC collected
by VDN 24101.

If VDN 24102 is monitored by the cstaMonitorCallsViaDevice( ) service from
any client and station 24103 is monitored by the cstaMonitorDevice( )
service, the 16 digits collected by VDN 24101 will be reported in the
Delivered Event Report (Call Delivered to a Station Device) sent to the
client monitoring station 24103 when the call is routed to the station.  If
the client application is only interested in the events reported for
station 24103, call filters can be used in the cstaMonitorCallsViaDevice( )
service to filter out all event reports from VDN 24102.  This will not
affect the UEC sent to the client monitoring station 24103.

Whether the station 24103 is monitored or not, the 16 digits will NOT be
reported again in the Delivered Event Report (Call Delivered to a Station
Device) for VDN 24102 when the call is delivered to station 24103.

If VDN 24102 is NOT monitored by the cstaMonitorCallsViaDevice( ) service
from any client, the 16 digits collected by VDN 24101 will NOT be reported.
Monitoring VDN 24102 (with or without call filters) is required for the
client monitoring station 24103 to receive the UEC collected by VDN 24101.



Call Scenario 2

VDN 24201 is mapped to vector 11 and vector 11 has the following steps:

     1. collect 10 digits after announcement extension 2000

     2. route to 24202

     3. stop

VDN 24202 is mapped to vector 12 and vector 12 has the following steps:

     1. collect 16 digits after announcement extension 3000

     2. route to 24203

     3. stop

VDN 24203 is mapped to vector 13 and vector 13 has the following steps:

     1. queue to main split 2 priority m

     2. stop

where split 2 is a vector controlled ACD split that has agent extensions
24301, 24302, 24303.

When a call arrives at VDN 24201, the caller hears an announcement and the
switch waits for the caller to enter 10 digits.  After the 10 digits are
collected in time, the call is routed to VDN 24202.  When the call arrives
at VDN 24202, the caller hears an announcement and the switch waits for the
caller to enter 16 digits.  After the 16 digits are collected in time, the
call is routed to VDN 24203.  The VDN 24203 queues the call to ACD Split 2.
If the agent at station 24301 is available, the call is sent to station
24301.

VDN 24101 does not need to be monitored; the collected digits will NOT be
reported in the Delivered Event Report (Call Delivered to a ACD Device)
sent to a client monitoring VDN 24201.  This is because the Delivered Event
Report is sent before the digits are collected.

If  VDN 24202 is monitored by the cstaMonitorCallsViaDevice( ) service, the
10 digits collected by VDN 24201 will be reported in the Delivered Event
Report (Call Delivered to a ACD Device) sent to the client monitoring VDN
24202.

If  VDN 24203 is monitored by the cstaMonitorCallsViaDevice( ) service, the
16 digits collected by VDN 24202 will be reported in the Delivered Event
Report (Call Delivered to a ACD Device) sent to the client monitoring VDN
24203.  However, the 10 digits collected by VDN 24201 will NOT be reported
in the Delivered Event for VDN 24203.  The cstaMonitorCallsViaDevice( )
service reports only the most recent UEC.

If  VDN 24202 and VDN 24203 are both monitored by
cstaMonitorCallsViaDevice( ) services from any client and station 24301 is
monitored by the cstaMonitorDevice( ) service, only the 16 digits collected
by VDN 24202 will be reported in the Delivered Event Report (Call Delivered
to a Station Device) sent to the client monitoring station 24301.  The
cstaMonitorDevice( ) service will report only the UEC that is received by
the VDN that redirects calls to the station.  Note that in order to receive
the UEC for a station monitor, the VDN that receives the UEC and redirects
calls to the station must be monitored.  For example, if VDN 24203 is not
monitored by any client, cstaMonitorDevice( ) service on station 24301 will
not report the 16 digits collected by VDN 24202.

