# ppxAddListeners

Adds listeners to a connection.

#### Prototype

DWORD ppxAddListeners ( PPXHD ppxhd, PPX_MVIP_ADDR listeners[], unsigned count )

Argument | Description
ppxhd | Handle returned by ppxCreateConnection or by ppxOpenConnection.
listeners[] | Pointer to a PPX_MVIP_ADDR structure. The structure is defined as follows: typedef struct { DWORD switch_number; DWORD bus; DWORD stream; DWORD timeslot; } PPX_MVIP_ADDR Refer to the Details section for a description of these fields.
count | Number of listeners to add.

#### Return values

Return value | Description
SUCCESS |
CTAERR_DRIVER_ERROR | Underlying driver retrieved an unrecognized error. Call swiGetLastError to retrieve the MVIP device error code.
CTAERR_INVALID_HANDLE | ppxhd is not a valid connection handle.
CTAERR_NOT_FOUND | One of the listeners is not defined in the Point-to-Point Switching configuration file.
CTAERR_OUT_OF_MEMORY | Unable to allocate memory.
CTAERR_SVR_COMM | Natural Access server communication error.
PPXERR_COMM_FAILURE | Problems were encountered when communicating with the PPX server.
PPXERR_DISABLED | Switch number specified was disabled.
PPXERR_DRIVER_OPEN_FAILED | Driver open failed, or the driver DLL or device was not found.
PPXERR_INVALID_COUNT | Number of supplied listeners is less than count.
PPXERR_INVALID_SWITCH | Switch number specified is inaccessible from the specified bus:stream:timeslot.
PPXERR_NO_PATH | Could not find a path from talker to one of the listeners assigned to the connection.
PPXERR_NOT_LISTENER | One of the listeners is incapable of receiving output from the connection.
SWIERR_INVALID_STREAM | One or more of the streams specified is invalid.
SWIERR_INVALID_TIMESLOT | One or more of the timeslots specified is invalid.

#### Details

ppxAddListeners adds listeners to a connection. If the connection already has a talker attached, switch connections are made to connect the listeners to the talker. If the talker and listeners are on different boards, telephony bus timeslots are used to make the connection.

If no talker is attached, the listeners have the default pattern of the connection sent to them.

The PPX_MVIP_ADDR structure contains the following fields:

Field | Description
--- | ---
switch_number | Switch number of the board as defined in ppx.cfg.
bus | Acceptable values are: MVIP95_MVIP_BUS MVIP95_LOCAL_BUS
stream | The stream number of the listener.
timeslot | The timeslot of the listener.

Refer to Adding listeners to a connection for more information.

#### See also

ppxRemoveListeners, ppxSetDefaultPattern, ppxSetTalker

#### Example

DWORD KeepOnHold( MYCONTEXT *cx )
{
DWORD e;
unsigned port_id;
CTA_EVENT event;
port_id = cx->id;
if( cx->conn_state != CTX_ONHOLD )
{
/* Need to add as a listener to the hold message
* connection.
*/
cx->conn_state = CTX_ONHOLD;
listeners[port_id].switch_number = cx->swi;
listeners[port_id].bus = MVIP95_LOCAL_BUS;
listeners[port_id].stream = 1;
listeners[port_id].timeslot = cx->time_slot;
e = ppxAddListeners( ppxhd[HOLD_MSG],
&listeners[port_id], 1 );
if (e != SUCCESS)
{
return e;
}
}
}