Conference Functions

Windows Conferencing API

# Conference Functions

## ConferenceConnect

    DWORD WINAPI ConferenceConnect(
    	HCONF    * phConf,
    	LPCONFADDR lpConfAddr,
    	LPCONFINFO lpConfInfo,
    	LPCONFNOTIFY lpConfNotify);

The ConferenceConnect function establishes a conference connection between two systems.

- If the function succeeds, the return value is CONFERR_SUCCESS.

  If there was a problem, the return value is one of the CONFERR values, such as:

  CONFERR_INVALID_HCONF | The value pointed to by phConf is invalid
  CONFERR_INVALID_PARAMETER | One of the other parameters or their fields is not valid

phConf
  Points to an HCONF that can be used to identify the conference. If the value pointed to by phConf is set to NULL, a new conference is created and the new conference identifier is returned through this parameter. If it is initially set to a valid conference identifier, the node associated with lpConfAddr is added to that existing conference.
lpConfAddr
  Points to a CONFADDR structure that indicates the address of the machine to connect to.
lpConfInfo
  Points to a CONFINFO structure that contains the initial conference settings.
lpConfNotify
  Points to a CONFNOTIFY structure that contains the notification callback information.

This function can be used to establish a new conference or add another user to an existing conference.

The callback routine receives the following notifications as a result of this function:

CONFN_CONFERENCE_INIT | The function parameters have been validated and connection request is being processed. This notification is not received when adding users to an existing conference.
CONFN_CONFERENCE_START | The conference has officially started.
CONFN_CONFERENCE_ERROR | An error was encountered when attempting to create the conference.

See also ConferenceDisconnect, CONFNOTIFYPROC, CONFADDR, CONFINFO CONFNOTIFY

## ConferenceDisconnect

    DWORD WINAPI ConferenceDisconnect(
    	HCONF hConf);

The ConferenceDisconnect function stops an existing conference.

- The return value is CONFERR_SUCCESS if the function succeeded or CONFERR_INVALID_HCONF if hConf is not a valid conference.

hConf
  Specifies the conference to stop.

If the conference was successfully terminated, the callback receives a CONFN_CONFERENCE_STOP notification.

See also ConferenceConnect CONFNOTIFYPROC

## ConferenceGetInfo

    DWORD WINAPI ConferenceGetInfo(
    	HCONF  hConf,
    	DWORD  dwCode,
    	LPVOID lpv);

The ConferenceGetInfo function obtains information about a conference or the users in a conference.

- If the function succeeds in obtaining the information, the return value is CONFERR_SUCCESS.

  If the return value is CONFERR_BUFFER_TOO_SMALL, then the DWORD pointed to by lpv contains the size of the buffer necessary to hold the data.

hConf
  The HCONF used to identify the conference.
dwCode
  Indicates the type of information to put into the buffer. See the table below for valid values.
lpv
  Points to a buffer that will be modified to contain the information requested. The first 4 bytes must be set to indicate the total size of the buffer. This will be modified, if the function succeeds, to indicate the amount actually used.

The following table describes the dwCode values and associated structures.

dwCode | lpv (structure) | Description
CONF_GET_USER | CONFUSERINFO | Get information on a specific user. On entry, dwUserId must be a valid user identifier or 0 to obtain the data for the local user.
CONF_ENUM_USER | CONFUSERINFO | Enumerate the users in a conference. On entry, dwUserId must be 0 to get the first user data, or the previous user identifier to get the next one in the list.
CONF_GET_CONF | CONFINFO | Get conference information. On entry, hConf must be the handle of an existing conference or NULL to get the data for the default conference.
CONF_ENUM_CONF | CONFINFO | Enumerate existing conferences. On entry, hConf must be 0 to get data for the first conference, or the hConf from the previous call to get the next one.
CONF_ENUM_PEER | CONFDEST | Enumerate the peer users for an application in a conference. On entry, dwUserId must be 0 to get the first peer information, or the previous user identifier to get the next one in the list.
CONF_GET_RECDIR | CONFRECDIR | Get the default directory for received files.
CONF_GET_FILEINFO | CONFFILEINFO | Get file transfer progress information. On entry, dwFileId is the file identifier provided in the notification callback.

On entry to this routine, the DWORD pointed to by lpv (the first four bytes) must be set to the size, in bytes, of the appropriate structure.

See also ConferenceSetInfo

## ConferenceSetInfo

    DWORD WINAPI ConferenceSetInfo(
    	HCONF  hConf,
    	DWORD  dwCode,
    	LPVOID lpv);

The ConferenceSetInfo function changes conference settings.

- If the function succeeds in setting the information, the return value is CONFERR_SUCCESS.

hConf
  The HCONF used to identify the conference. This parameter may be NULL.
dwCode
  Indicates the type of information in the buffer. See the table below for valid values.
lpv
  Points to a buffer that holds the new conference data. The first 4 bytes must be set to indicate the total size of the structure.

The following table describes the valid dwCode values and associated structures.

dwCode | lpv (structure) | Description
CONF_SET_RECDIR | CONFRECDIR | Set the default directory for receiving files. On entry, szRecDir is a null-terminated pathname to a valid directory. This change affects all subsequent file transfers on the local machine.
CONF_SET_GUID | CONFGUID | Register the data specified in the CONFGUID structure. If the pszApplication and pszCommandLine are both empty strings, the entry for the guid is removed from the registry.

See also ConferenceGetInfo

## ConferenceSendData

    DWORD WINAPI ConferenceSendData(
    	HCONF      hConf,
    	LPCONFDEST lpConfDest,
    	LPVOID     lpv,
    	DWORD      cb,
    	DWORD      dwFlags);

The ConferenceSendData function sends data to participants in a conference.

- The return value is CONFERR_SUCCESS if the data was sent successfully.

hConf
  The HCONF used to identify the conference.
lpConfDest
  Points to a CONFDEST structure

  dwSize | must be set to the size of this structure
  dwFlags | this field should be set to 0
  dwUserId | the destination identifier for a single user, or 0 to indicate all participants in the conference
  dwReserved | this field is reserved and should be set to 0
  guid | the unique application identifier GUID

lpv
  Points to the buffer of data to be sent.
cb
  The number of bytes in the buffer pointed to by lpv.
dwFlags
  Reserved for future use.

Notifications of data transmission are made through the notification callback routine for the process. The process receiving the data receives the CONFN_DATA_RECEIVED notification while the sending process gets CONFN_DATA_SENT. In each case, the dwParam parameter is the number of bytes pointed to by lpv2, while lpv1 is the LPCONFDEST.

The receiving application must have a callback registered with the same guid as specified in the lpConfDest.

The dwFlags field of the CONFDEST structure pointed to by lpv1 may have one or more of the following flags set:

CONF_DF_BROADCAST | The data was broadcast to all users
CONF_DF_PRIVATE | The data was sent directly from one machine to another
CONF_DF_DATA_SEGMENT_BEGIN | This is the start of a data block
CONF_DF_DATA_SEGMENT_END | This is the end of a data block

If the size of the data block is under 4,000 bytes, the data will normally not be broken up into smaller packets and both the CONF_DF_DATA_SEGMENT_BEGIN and CONF_DF_DATA_SEGMENT_END bits will be set.

See also ConferenceSendFile, ConferenceSetNotify, CONFDEST CONFNOTIFYPROC

## ConferenceSendFile

    DWORD WINAPI ConferenceSendFile(
    	HCONF      hConf,
    	LPCONFDEST lpConfDest,
    	LPCTSTR    szFileName,
    	DWORD      dwFlags);

The ConferenceSendFile function sends a file to one or more participants in a conference.

- The return value is CONFERR_SUCCESS if the file was sent successfully.

  CONFERR_FILE_NOT_FOUND is returned if the file or pathname is invalid.

  CONFERR_INVALID_PARAMETER is returned if there was a problem the dwFlags parameter or any of the members in the structure pointed to by lpConfDest.

hConf
  The HCONF used to identify the conference.
lpConfDest
  Points to a CONFDEST structure

  dwSize | must be set to the size of this structure
  dwFlags | this field should be set to 0
  dwUserId | the destination identifier for a single user, or 0 to indicate all participants in the conference
  dwReserved | this field is reserved and should be set to 0
  guid | this field is not used and should be set to 0

szFileName
  The null terminated name of the file to send.
dwFlags
  Specifies the options used to send the file. This parameter can be a combination of any of the following:

  CONF_SF_NOWAIT | The function should start the file transfer immediate and return without waiting for it to complete.
  CONF_SF_NOUI | The default progress indicator should not be used.
  CONF_SF_NOCOMPRESS | The file should not be compressed.

Notifications of file transfers are made through the CONFNOTIFYPROC for the process. The notification callback receives the following information:

dwParam | the unique file identifier (dwFileId).
lpv1 | a pointer to the CONFDEST structure
lpv2 | a pointer to the CONFFILEINFO

See also ConferenceSendData, ConferenceGetInfo, CONFDEST

## ConferenceCancelTransfer

    DWORD WINAPI ConferenceCancelTransfer(
    	HCONF hConf,
    	DWORD dwFileId);

The ConferenceCancelTransfer function stops the transfer of a file.

- The return value is CONFERR_SUCCESS if the request was successfully processed.

hConf
  The HCONF used to identify the conference.
dwFileId
  The value used to identify a file transfer. This is the dwParam parameter passed to the callback for any of the CONFN_FILESEND or CONFN_FILERECEIVE notifications.

Note that it is possible for the transfer to complete before the request to cancel has been processed.

See also ConferenceSendFile CONFDEST,

## ConferenceShareWindow

    DWORD WINAPI ConferenceShareWindow(
    	HCONF hConf,
    	HWND  hwnd,
    	DWORD dwCode);

The ConferenceShareWindow function shares an application window to the participants of the specified conference.

- The function returns one of the following values

  CONFERR_SUCCESS | The function was successful
  CONFERR_NO_APP_SHARING | Application sharing is not currently active
  CONFERR_NOT_SHARED | The hwnd is not shared
  CONFERR_NOT_SHAREABLE | The hwnd can not be shared
  CONFERR_ALREADY_SHARED | The hwnd is already shared

hConf
  Identifies the conference in which to share the window. If this is NULL, the default conference is used.
hwnd
  Identifies the window to share.
dwCode
  Specifies the sharing option. This must be one of:

  CONF_SW_SHARE | Share the application associated with the hwnd
  CONF_SW_UNSHARE | Stop sharing the application associated with the hwnd
  CONF_SW_SHAREABLE | Check if the hwnd is capable of being shared
  CONF_SW_IS_SHARED | Check if the hwnd is currently shared

The notification callback routine receives CONFN_WINDOW_SHARED or CONFN_WINDOW_UNSHARED when a window changes its sharing status. The dwParam is the window handle. A dwParam of 0 indicates application sharing has stopped.

See also CONFNOTIFYPROC

## ConferenceLaunchRemote

    DWORD WINAPI ConferenceLaunchRemote(
    	HCONF      hConf,
    	LPCONFDEST lpConfDest,
    	DWORD      dwReserved);

The ConferenceLaunchRemote function informs a remote system it should attempt to start an application that has been registered.

- The return value is CONFERR_SUCCESS if the request was successfully processed.

hConf
  The HCONF used to identify the conference.
lpConfDest
  Points to a CONFDEST structure

  dwSize | must be set to the size of this structure
  dwFlags | this field should be set to 0
  dwUserId | the destination identifier for a single user, or 0 to indicate all participants in the conference
  dwReserved | this field is reserved and should be set to 0
  guid | the unique application identifier GUID

dwReserved
  This parameter is reserved for future use and should be set to 0.

When a destination node receives this notification, it searches the registry for a matching guid. If an entry for an application is found, it attempts to start it, based on the data supplied when it was registered.

There is no notification given if the guid is not found or the application fails to start.

Note that a return value of CONFERR_SUCCESS does not guarantee the remote application has been started.

To detect when a remote application has joined the conference, it could register a callback with a guid, usually the same as the one used to launch the application. When the remote version of the application is launched and establishes its callback with the same guid the local application will receive a CONFN_PEER_ADDED notification.

See also ConferenceSetInfo, ConferenceSetNotify, CONFDEST,

## ConferenceListen

    DWORD WINAPI ConferenceListen(
    	DWORD dwReserved);

The ConferenceListen function starts the conferencing system in background mode, allowing it to accept incoming calls.

- The return value is CONFERR_SUCCESS if the request was successfully processed.

dwReserved
  This parameter is reserved for future use and should be set to 0.

Note that the user can set the option to automatically accept incoming calls or shut down the conferencing system.

There is no effect if conferencing is already running.

## ConferenceSetNotify

    DWORD WINAPI ConferenceSetNotify(
    	HCONF        hConf,
    	LPCONFNOTIFY lpConfNotify,
    	HCONFNOTIFY * phConfNotify);

The ConferenceSetNotify function establishes a notification callback routine for an application

- The return value is CONFERR_SUCCESS if the request was successfully processed.

hConf
  The HCONF used to identify the conference. If this is NULL, the notification procedure will receive events for all conferences, otherwise the callback will be automatically removed when the conference is terminated.
lpConfNotify
  Points to a CONFNOTIFY structure.

  dwSize | must be set to the size of this structure
  dwUser | this field is available for the application's use and will be passed back through the notification callback function
  dwFlags | reserved for future use
  guid | the field should be set to 0 unless the application intends to receive data sent via ConferenceSendData
  pfnNotifyProc | a pointer to the notification callback function (See CONFNOTIFYPROC)

phConfNotify
  Points to a HCONFNOTIFY identifier that must be used to remove the notification procedure. (See ConferenceRemoveNotify)

See also ConferenceRemoveNotify CONFNOTIFY, HCONFNOTIFY, CONFNOTIFYPROC,

## ConferenceRemoveNotify

    DWORD WINAPI ConferenceRemoveNotify(
    	HCONF       hConf,
    	HCONFNOTIFY hConfNotify);

The ConferenceRemoveNotify function requests that a procedure, established by ConferenceSetNotify no longer receive notifications about conferencing events.

- The return value is CONFERR_SUCCESS if the request was successfully processed.

hConf
  The HCONF used to identify the conference.
hConfNotify
  The HCONFNOTIFY returned from a call to ConferenceSetNotify.

See also ConferenceSetNotify, CONFNOTIFY, HCONFNOTIFY, CONFNOTIFYPROC,

## CONFNOTIFYPROC

    DWORD WINAPI ConfNotifyProc(
    	HCONF  hConf,
    	DWORD  dwCode,
    	DWORD  dwParam,
    	LPVOID lpv1,
    	LPVOID lpv2,
    	DWORD  dwUser);

CONFNOTIFYPROC is an application-defined callback function for conference events.

- The function should normally return 0.

hConf
  Provides a conference identifier to the ConfNotifyProc.
dwCode
  Specifies the conference event that occurred. See the comments section for a table of valid notification codes.
dwParam
  Specifies a parameter for the event corresponding to dwCode.
lpv1
  Specifies a parameter for the event corresponding to dwCode.
lpv2
  Specifies a parameter for the event corresponding to dwCode.
dwUser
  The application specific value specified in the CONFNOTIFY structure.

The following is a table of notification codes with their associated parameter definitions.

dwCode | dwParam | lpv1 | lpv2
CONFN_CONFERENCE_INIT | -- | LPCONFADDR | LPCONFINFO
CONFN_CONFERENCE_START | -- | -- | LPCONFINFO
CONFN_CONFERENCE_STOP | -- | -- | LPCONFINFO
CONFN_CONFERENCE_ERROR | -- | -- | LPCONFINFO
CONFN_USER_ADDED | dwUserId | -- | LPCONFUSERINFO
CONFN_USER_REMOVED | dwUserId | -- | LPCONFUSERINFO
CONFN_USER_UPDATE | dwUserId | -- | LPCONFUSERINFO
CONFN_PEER_ADDED | dwUserId | LPCONFDEST | --
CONFN_PEER_REMOVED | dwUserId | LPCONFDEST | --
CONFN_WINDOW_SHARED | HWND | -- | --
CONFN_WINDOW_UNSHARED | HWND | -- | --
CONFN_DATA_RECEIVED | the number of bytes pointed to by lpv2 | LPCONFDEST | pointer to data received
CONFN_DATA_SENT | the number of bytes pointed to by lpv2 | LPCONFDEST | pointer to data sent
CONFN_FILESEND_START | dwFileId | LPCONFDEST | LPCONFFILEINFO
CONFN_FILESEND_PROGRESS | dwFileId | LPCONFDEST | LPCONFFILEINFO
CONFN_FILESEND_COMPLETE | dwFileId | LPCONFDEST | LPCONFFILEINFO
CONFN_FILESEND_ERROR | dwFileId | LPCONFDEST | LPCONFFILEINFO
CONFN_FILERECEIVE_START | dwFileId | LPCONFDEST | LPCONFFILEINFO
CONFN_FILERECEIVE_PROGRESS | dwFileId | LPCONFDEST | LPCONFFILEINFO
CONFN_FILERECEIVE_COMPLETE | dwFileId | LPCONFDEST | LPCONFFILEINFO
CONFN_FILERECEIVE_ERROR | dwFileId | LPCONFDEST | LPCONFFILEINFO

The values of lpv1 and lpv2 must not be used past the return from this callback. If necessary, the data pointed to by the structures may be copied.

See also ConferenceConnect CONFNOTIFY

[Previous] [Up One Level] [Next]