SetConferenceGroupIds

The SetConferenceGroupIds API procedure is used to define one or more conference group IDs for each phone line.

The media engine uses the concept of conference session IDs. Conference session IDs can be assigned to individual phone lines using the SetConferenceGroupIds API procedure. When your application places a phone line into the conference state using the ConferenceLine API procedure, the phone line will share full duplex audio data with any other phone lines that have the same congference IDs.

By assigning one or more conference group IDs to phone lines, your VOIP application can create simple to very complex conference relationships between phone lines.

By default each phone line belongs to the default conference session "0". In this case, placing all lines into conference mode will allow all lines to share full duplex audio data between them. This corresponds to a single conference session model.

If you wanted to group lines into separate individual conference sessions, you would call the SetConferenceGroupIds API procedure to set specific conference session IDs for whatever phone lines you would want to use. Then you would place all lines of interest into the conference mode using the ConferenceLine API procedure. For additional details, see the remarks section at the bottom of this topic.

TELEPHONY_RETURN_VALUE SetConferenceGroupIds(

SIPHANDLE hStateMachine,

int PhoneLine,

int NumConferenceGroupIds,

char **ppConferenceGroupIds

);

Parameters:

hStateMachine

[in] The handle to the telephony engine. This is the handle that was returned by a previous call to the StartSipTelephony procedure.

PhoneLine

[in] The zero based phone line used to set conference IDs.

NumConferenceGroupIds

[in] Specifies the number of conference group IDs you will be setting for the specified phone line.

ppConferenceGroupIds

[in] An array of pointers to conference group ID strings. This array must be the same length as the value specified for parameter NumConferenceGroupIds. Conference group IDs are maintained as strings and can be any values your application requires. Any phone lines sharing the same conference session IDs will belong to the same conference group when the phone line is placed into conference mode using the ConferenceLine API procedure.

Return Value:

If the function succeeds, the return value will be SipSuccess.

If the function fails, the return value will be one of the following values as specified by the TELEPHONY_RETURN_VALUE data type.

Value	Description
SipCallFailure	This is a generic "catch all" API error. If an error condition is not specified by any other API error value, this error will be returned.
SipInvalidHandle	An API procedure was passed an invalid handle. The telephony engine attempts to verify user specified telephony handles and returns this error when an invalid handle is detected.
SipBadPhoneLine	A telephony operation was specified using an invalid phone line. Phone lines are numbered starting from zero.
SipNoCallActive	An API operation was being performed on a phone line. However, there is no active call on the specified phone line.
SipConferenceNotEnabled	Call conferencing is not enabled. For additional details, see the CallConferenceEnabled startup parameter in the START_SIP_TELEPHONY_PARAMS startup structure.

Remarks:

Call conference support must be enabled in the media engine when it is started. Your media engine license must also support call conference capabilities. For additional details, see the CallConferenceEnabled startup parameter in the START_SIP_TELEPHONY_PARAMS startup structure.

In general, applications can call the SetConferenceGroupIds API procedure any time except when a phone line is already in conference mode as the result of calling the ConferenceLine API procedure.

Application software can define as many individual conference session ID relationships between phone lines as required. There are no limitations place on the number of conference session IDs per phone line or their values.

By default, all phone lines belong to the single conference group "0". If you call the ReStartSipTelephony API procedure, all phone line conference IDs will resort back to the default power-up state.