About Conferencing APIs

The purpose of the high-level Conferencing Application Program Interface is to enable productivity applications to take advantage of existing conferencing features while requiring minimal development effort.

The functions enabled by these APIs can be grouped into three areas:

•	Managing conference information

•	Sharing applications

•	Transferring data

It is not intended that these APIs be used to streamline development of truly distributed conferencing applications. The Multipoint Communication Services (MCS) and Generic Call Control (GCC) APIs are available to applications for this purpose. The MCS and GCC APIs are beyond the scope of this document.

It should be noted that almost all of the APIs are synchronous. In general, the function call will not return until the specified action is complete. If the application requires the process to not lose control for an extended period of time, it should start a separate thread to handle the task.


Managing conference information

An application can start a call, terminate a call, or find out if a call is active. An application can also be notified when a call begins or ends.

The APIs for managing conference information are:

•	ConferenceConnect

•	ConferenceDisconnect

•	ConferenceGetInfo

•	ConferenceSetInfo

•	ConferenceLaunchRemote

ConferenceConnect and ConferenceDisconnect are used to create and terminate a conferencing call. Information about the call can be obtained using ConferenceGetInfo and modified through ConferenceSetInfo. A callback function can be established to receive notifications about changes in the conference.


Sharing applications

Application-sharing APIs are provided to allow an application window to be shared or unshared without invoking the system applet for this purpose.

The APIs for application sharing are:

•	ConferenceShareWindow

•	ConferenceIsWindowShared

Applications are notified through the notification callback function for the conference when their sharing status changes.

Although application sharing is currently done at the task level rather than the window level, all of these APIs use window handles (HWNDs) to identify the application. This is done for programming convenience and to allow for future versions of Microsoft NetMeeting that may support sharing individual windows.


Transferring data

Applications can transfer data and files between users in the call.

The APIs for data transfer are:

•	ConferenceSendData

•	ConferenceSendFile

ConferenceSendData can be used to send data to a specific application of a conference participant. The notification callback function for the conference is informed of incoming data and file transfer progress. The information can be marked for use by a specific application.


ConferenceConnect

The ConferenceConnect function establishes a conference connection between two systems.

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

Parameters

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.

Return Values

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

Remarks

This function can be used to establish a new conference or add another user to an existing conference. Since the function does not return until the connection has been successfully established (or an error occurred), the application must set up a callback routine to process the notifications and call ConferenceDisconnect to abort the connection attempt.

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


ConferenceDisconnect

The ConferenceDisconnect function stops an existing conference.

DWORD WINAPI ConferenceDisconnect(
HCONF hConf
);

Parameters

hConf

Specifies the conference to stop.

Return Values

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

Remarks

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

See Also

ConferenceConnect CONFNOTIFYPROC


ConferenceGetInfo

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

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

Parameters

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.

Return Values

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.

Remarks

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_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

The ConferenceSetInfo function changes conference settings.

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

Parameters

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.

Return Values

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

Remarks

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

dwCode	lpv (structure)	Description
CONF_SET_NOTIFY	CONFNOTIFY	Set the notification callback procedure for a conference. On entry, pfnNotifyProc is the address of a CONFNOTIFYPROC for the process and guid is the unique identifier for the application.
CONF_REMOVE_NOTIFY	CONFNOTIFY	The callback procedure should not receive any more notifications. On entry, pfnNotifyProc is the address of a CONFNOTIFYPROC that was set using CONF_SET_NOTIFY.
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

The ConferenceSendData function sends data to participants in a conference.

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

Parameters

hConf

The HCONF used to identify the conference.

lpConfDest

Points to a CONFDEST structure that indicates the specific user and application that is to receive the data.

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.

Return Values

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

Remarks

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.

See Also

ConferenceSendFile, CONFDEST CONFNOTIFYPROC


ConferenceSendFile

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

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

Parameters

hConf

The HCONF used to identify the conference.

lpConfDest

Points to a CONFDEST structure that indicates the specific user and application that is to receive the file.

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.

Return Values

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.

Remarks

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


ConferenceShareWindow

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

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

Parameters

hwnd

Identifies the window to share.

hConf

Identifies the conference in which to share the window. If this is NULL, the default conference is used.

dwFlags

Specifies the sharing options. This must be either CONF_SW_SHARE or CONF_SW_UNSHARE.

Return Values

If the window's sharing status is successfully changed, the function returns CONFERR_SUCCESS.

Remarks

The notification callback routine receives CONFN_WINDOW_SHARED or CONFN_WINDOW_UNSHARED when a window changes its sharing status.

See Also

ConferenceIsWindowShared,


ConferenceIsWindowShared

The ConferenceIsWindowShared function determines whether the specified window is shared.

BOOL WINAPI ConferenceIsWindowShared(
HWND hwnd,
HCONF * phConf
);

Parameters

hwnd

Identifies the window to test.

phConf

Points to the buffer which will contain the conference identifier in which the window is shared. This parameter may be NULL if the conference information is not required.

Return Values

If the window indicated by hwnd is currently shared, the return value is TRUE and the HCONF pointed to by phConf will contain the identifier for the conference, otherwise the return value is FALSE and the data pointed to by phConf is not modified.

See Also

ConferenceShareWindow


ConferenceLaunchRemote

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

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

Parameters

hConf

The HCONF used to identify the conference.

lpConfDest

Points to a CONFDEST structure that indicates the destination application and user(s).

dwReserved

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

Return Values

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

Remarks

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

Note that a return value of CONFERR_SUCCESS does not guarantee the remote application has been started. The local process should monitor CONFN_PEER_ADDED notifications to detect when the remote process has joined the conference.

See Also

ConferenceSetInfo, CONFDEST,


CONFNOTIFYPROC

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

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

Parameters

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.

Return Values

The function should normally return 0.

Remarks

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	--	LPCONFADDR	LPCONFINFO
CONFN_CONFERENCE_STOP	--	LPCONFADDR	LPCONFINFO
CONFN_CONFERENCE_ERROR	--	--	--
CONFN_USER_ADDED	dwUserId	LPCONFADDR	LPCONFUSERINFO
CONFN_USER_REMOVED	dwUserId	LPCONFADDR	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


Conference Error Codes

The return value of a conferencing function can be any one of the following values:

typedef DWORD CONFERR;

Remarks

Error Code	Description
CONFERR_ACCESS_DENIED	Access to an object (file, user, etc.) was denied.
CONFERR_BUFFER_TOO_SMALL	The buffer pointed to by a parameter is not large enough for the operation
CONFERR_ENUM_COMPLETE	Enumeration complete
CONFERR_FILE_NOT_FOUND	The file was not found
CONFERR_FILE_RECEIVE_ABORT	The receiving of the file was canceled.
CONFERR_FILE_SEND_ABORT	The file send was canceled
CONFERR_FILE_TRANSFER	There was a problem transferring the file
CONFERR_INVALID_BUFFER	The buffer pointed to by a parameter is not valid for read/write.
CONFERR_INVALID_HCONF	The hConf parameter is not valid.
CONFERR_INVALID_PARAMETER	One of the calling parameters is incorrect.
CONFERR_OUT_OF_MEMORY	A function could not allocate sufficient memory to complete the operation.
CONFERR_PATH_NOT_FOUND	The path was not found
CONFERR_RECEIVE_DIR	There was a problem with the receive directory
CONFERR_SUCCESS	The function completed the requested operation successfully


CONFADDR

A CONFADDR structure describes the address of another machine.

typedef struct tagConfAddr {

DWORD dwSize;

DWORD dwAddrType;

union {

DWORD dwIp;

PTSTR psz;

};

} CONFADDR;

Members

dwSize

Specifies the total size of the structure in bytes.

dwAddrType

Specifies the type of address following this member. This can be one of the following:

CONF_ADDR_IP	dwIp holds the IP address

CONF_ADDR_MACHINENAME	psz is the name of a machine on the local network

CONF_ADDR_PSTN	psz is the TAPI canonical telephone number

CONF_ADDR_UNKNOWN	neither dwIp nor psz are used

dwIp

The IP address as a set of 4 bytes.

psz

A pointer to the address as a null-terminated string. The definition of this depends upon the dwAddrType field.

See Also

ConferenceConnect


CONFDEST

A CONFDEST structure defines a destination node within a conference.

typedef struct tagConfDest {

DWORD dwSize;

DWORD dwFlags;

DWORD dwUserId;

GUID  guid;

} CONFDEST;

Members

dwSize

Specifies the structure size in bytes.

dwFlags

Specifies the destination flags for the transfer. This can be one of the following:

CONF_DF_BROADCAST	data was broadcast to everyone in the conference

CONF_DF_PRIVATE	data was privately sent

dwUserId

Specifies a unique user identification code. If this is 0, it implies everyone in the conference.

guid

Specifies a unique application identifier GUID. The fields of this structure can be set to 0, if not required.

See Also

ConferenceSendData, ConferenceSendFile GUID


CONFFILEINFO

A CONFFILEINFO structure describes a file in the process of being transferred.

typedef struct tagConfFileInfo {

DWORD dwSize;

DWORD dwFileId;

DWORD dwFileSize;

DWORD dwBytesTransferred;

DWORD dwFileAttributes;

FILETIME ftCreationTime;

FILETIME ftLastAccessTime;

FILETIME ftLastWriteTime;

TCHAR szFileNameSrc[MAX_PATH];

TCHAR szFileNameDest[MAX_PATH];

} CONFFILEINFO;

Members

dwSize

Specifies the structure size in bytes.

dwFileId

Specifies a unique identifier for the file.

dwFileSize

Specifies the size of the file, in bytes.

dwBytesTransferred

Specfies the number of bytes that have been transferred.

dwFileAttributes

Specifies the DOS file attributes.

ftCreationTime

Specifies the creation time/date of the file.

ftLastAccessTime

Specfies the last time/date the file was accessed.

ftLastWriteTime

Specifies the last time/date the file was modified.

szFileNameSrc

Specifies the original file name.

szFileNameDest

Specifies the destination file name. This is only valid for the receiving process and may be not be the same as the original file name

See Also

ConferenceGetInfo, ConferenceSendFile


CONFGUID

A CONFGUID structure specifies the parameters passed to CreateProcess when an active conference receives a notification to invoke the application associated with the guid.

typedef struct tagConfGuid {

DWORD   dwSize;

GUID    guid;

LPCTSTR pszApplication;

LPCTSTR pszCommandLine;

LPCTSTR pszDirectory;

} CONFGUID;

Members

dwSize

Specifies the structure size in bytes.

guid

Specifies the unique application identifier GUID.

pszApplication

Pointer to a null-terminated string that specifies the module to execute. The string should specify the full path and filename of the module to execute. If pszApplication is NULL, the module name must be the first white space-delimited token in the pszCommandLine string.

pszCommandLine

Pointer to a null-terminated string that specifies the command line to execute. The pszCommandLine field can be NULL. In that case, the function uses the string pointed to by pszApplication as the command line.

pszDirectory

Points to a null-terminated string that specifies the current drive and directory for the process. The string must be a full path and filename that includes a drive letter. This field may be NULL.

See Also

ConferenceSetInfo, ConferenceLaunchRemote,


CONFINFO

A CONFINFO structure defines the current conference settings.

typedef struct tagConfInfo {

DWORD dwSize;

DWORD dwFlags;

DWORD dwMediaType;

DWORD dwGCCID

HCONF hConf;

DWORD cUsers;

CONFNOTIFYPROC pfnNotifyProc;

TCHAR szConferenceName[CONF_MAX_CONFERENCENAME];

} CONFINFO;

Members

dwSize

Specifies the structure size in bytes.

dwFlags

Specifies the current conference options.

dwMediaType

Specifies the media type. This may be a combination of one or more of the following:

CONF_MT_DATA	Data conference

CONF_MT_AUDIO	Audio is available

CONF_MT_VIDEO	Video is available

Use CONF_MT_ALL to specify all supported types.

dwGCCID

Reserved for future use.

hConf

The handle of the current conference.

cUsers

The number of users in the conference.

pfnNotifyProc

Specifies the notification callback routine (see CONFNOTIFYPROC)

szConferenceName

Specifies the name of the conference.

See Also

ConferenceGetInfo ConferenceConnect


CONFNOTIFY

A CONFNOTIFY structure specifies the notification callback routine for a process in a conference.

typedef struct tagConfNotify {

DWORD dwSize;

DWORD dwFlags;

CONFNOTIFYPROC pfnNotifyProc;

GUID guid;

} CONFNOTIFY;

Members

dwSize

Specifies the structure size in bytes.

dwFlags

Reserved for future use

pfnNotifyProc

Specifies the address of the notification callback routine.

guid

Specifies the unique application identifier GUID.

Remarks

If a non-zero guid is specified, then the callback will receive notifications of incoming data for the duration of the conference.

See Also

ConferenceGetInfo, ConferenceConnect, ConfNotifyProc


CONFRECDIR

A CONFRECDIR structure describes the default directory for received files.

typedef struct tagConfRecDir {

DWORD dwSize;

TCHAR  szRecDir[MAX_PATH];

} CONFRECDIR;

Members

dwSize

Specifies the structure size in bytes.

szRecDir

Specifies the full path of the default directory for received files.

Remarks

Note there is only one current receive directory for the local machine and it is saved across sessions.

See Also

ConferenceGetInfo, ConferenceSendFile


CONFUSERINFO

A CONFUSERINFO structure describes a single user in a conference.

typedef struct tagConfUserInfo {

DWORD dwSize;

DWORD dwUserId;

DWORD dwReserved;

TCHAR  szUserName[CONF_MAX_USERNAME];

} CONFUSERINFO;

Members

dwSize

Specifies the structure size in bytes.

dwUserId

Specifies a unique value to identify a user within a conference.

dwReserved

Reserved for future use. This must be 0.

szUserName

The null terminated string representing the user's name.

See Also

ConferenceGetInfo


GUID

The GUID structure holds a globally unique identifier (GUID), which identifies a particular object class and interface. This identifier is a 128-bit value. For more information about GUIDs, see the Remote Procedure Call (RPC) documentation or the OLE Programmer's Reference

Use the guidgen.exe utility to generate new values.

 typedef struct _GUID {

unsigned long   Data1;

unsigned short  Data2;

unsigned short  Data3;

unsigned char   Data4[8];

} GUID;

See Also

CONFDEST CONFGUID CONFNOTIFY


HCONF

This identifies a conference.

typedef HANDLE HCONF;

Remarks

A NULL hConf implies the default conference, if one is available.