Previous Up Index Next

Conference Functions


ConferenceCancelTransfer

DWORD WINAPI ConferenceCancelTransfer(
    HCONF hConf,
    DWORD dwFileId);

Stops the transfer of a file.

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

ConferenceConnect

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

Establishes a conference connection between two systems.

phConf
Address to an HCONF that identifies the conference. If this value 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 computer associated with lpConfAddr is added to that existing conference.
lpConfAddr
Address to a CONFADDR structure that contains the address of the computer to connect to.
lpConfInfo
Address to a CONFINFO structure that contains the initial conference settings.
lpConfNotify
Address to a CONFNOTIFY structure that contains the notification callback information.

This function can be used to establish a new conference or to 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 the 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, CONFADDR, CONFINFO, CONFNOTIFY, CONFNOTIFYPROC

ConferenceDisconnect

DWORD WINAPI ConferenceDisconnect(
    HCONF hConf);

Stops an existing conference.

hConf
The HCONF that identifies 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);

Obtains information about a conference or the users in a conference.

hConf
The HCONF used to identify the conference.
dwCode
The type of information to put into the buffer. See the table below for valid values.
lpv
Address to a buffer that will be modified to contain the information requested. The first four 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. If the function returns CONFERR_BUFFER_TOO_SMALL, the DWORD pointed to by this parameter will contain the size of the buffer necessary to hold the data.

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

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

See also ConferenceSetInfo

ConferenceLaunchRemote

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

Informs a remote system that it should attempt to start an application that has been registered.

hConf
The HCONF used to identify the conference.
lpConfDest
Address to a CONFDEST structure. The dwFlags field should be set to zero.
dwReserved
Reserved for future use; should be set to zero.

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);

Starts the conferencing system in background mode, allowing it to accept incoming calls.

dwReserved
Reserved for future use; should be set to zero.

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

This function has no effect if conferencing is already running.

ConferenceRemoveNotify

DWORD WINAPI ConferenceRemoveNotify(
    HCONF hConf,
    HCONFNOTIFY hConfNotify);

Requests that a procedure established by ConferenceSetNotify no longer receive notifications about conferencing events.

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

See also ConferenceSetNotify, CONFNOTIFY, CONFNOTIFYPROC, HCONFNOTIFY

ConferenceSendData

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

Sends data to participants in a conference.

hConf
The HCONF used to identify the conference.
lpConfDest
Address to a CONFDEST structure. The dwFlags field should be set to zero.
lpv
Address 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 process sending the data receives the CONFN_DATA_SENT notification. In each case, the dwParam parameter is the number of bytes pointed to by lpv2 parameter, while lpv1 points to the CONFDEST structure.

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

The dwFlags field of the CONFDEST structure pointed to by lpv1 can 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 computer 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 4000 bytes, the data will normally not be broken 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);

Sends a file to one or more participants in a conference.

hConf
The HCONF used to identify the conference.
lpConfDest
Address to a CONFDEST structure. The dwFlags and guid fields should be set to zero.
szFileName
The null-terminated name of the file to send.
dwFlags
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 immediately 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 structure 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 structure.

See also ConferenceGetInfo, ConferenceSendData, CONFDEST

ConferenceSetInfo

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

Changes conference settings.

hConf
The HCONF used to identify the conference. This parameter can be NULL.
dwCode
The type of information in the buffer. See the table below for valid values.
lpv
Address to a buffer that holds the new conference data. The first four 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 Sets the default directory for receiving files. On entry, the szRecDir value represents a null-terminated path to a valid directory. This change affects all subsequent file transfers on the local computer.
CONF_SET_GUID CONFGUID Registers the data specified in the CONFGUID structure. If pszApplication and pszCommandLine values are both empty strings, the entry for guid is removed from the registry.

See also ConferenceGetInfo

ConferenceSetNotify

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

Establishes a notification callback routine for an application.

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 removed automatically when the conference is terminated.
lpConfNotify
Address to a CONFNOTIFY structure.
phConfNotify
Address to an HCONFNOTIFY identifier that must be used to remove the notification procedure (see ConferenceRemoveNotify).

See also ConferenceRemoveNotify, CONFNOTIFY, CONFNOTIFYPROC, HCONFNOTIFY

ConferenceShareWindow

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

Shares an application window to the participants of the specified conference.

hConf
The conference in which to share the window. If this is NULL, the default conference is used.
hwnd
The window to share.
dwCode
The sharing option. This must be one of the following values:
CONF_SW_SHARE Share the application associated with hwnd.
CONF_SW_UNSHARE Stop sharing the application associated with hwnd.
CONF_SW_SHAREABLE Check if hwnd is capable of being shared.
CONF_SW_IS_SHARED Check if 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 field value is the window handle. A dwParam of zero indicates application sharing has stopped.

See also CONFNOTIFYPROC

CONFNOTIFYPROC

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

Indicates an application-defined callback function for conference events.

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

The following table lists 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 Number of bytes pointed to by lpv2. LPCONFDEST Pointer to data received.
CONFN_DATA_SENT 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 can be copied.

See also ConferenceConnect, CONFNOTIFY

Conference Error Codes

CONFERR

typedef DWORD CONFERR;

The return value of a conferencing function can be any one of the following values.
Error Code Description
CONFERR_ACCESS_DENIED Access to an object (file, user, and so on.) was denied.
CONFERR_ALREADY_SHARED The application is already shared.
CONFERR_BUFFER_TOO_SMALL The buffer pointed to by a parameter is not large enough for the operation.
CONFERR_ENUM_COMPLETE Enumeration is 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_ADDRESS The address is invalid or not found.
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_HWND The value passed to ConferenceShareWindow is not a valid hwnd.
CONFERR_INVALID_OPERATION The requested operation is not valid at this time.
CONFERR_INVALID_PARAMETER One of the calling parameters is incorrect.
CONFERR_NO_APP_SHARING Application sharing is not currently available.
CONFERR_NOT_SHARED The application window is not currently shared.
CONFERR_NOT_SHAREABLE The application window cannot be shared.
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.

Conference Structures

CONFADDR

typedef struct tagConfAddr {
    DWORD dwSize;
    DWORD dwAddrType;
    union {
        DWORD dwIp;
        PTSTR psz;
        };
} CONFADDR;

Describes the address of another computer.

dwSize
The total size of the structure, in bytes.
dwAddrType
The type of address following this member. This can be one of the following:
CONF_ADDR_IP The dwIp parameter holds the IP address.
CONF_ADDR_MACHINENAME The psz parameter is the name of a computer on the local network.
CONF_ADDR_PSTN The psz parameter is the TAPI canonical telephone number.
CONF_ADDR_UNKNOWN Neither dwIp nor psz is used.
dwIp
The IP address as a set of four 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

typedef struct tagConfDest {
    DWORD dwSize;
    DWORD dwFlags;
    DWORD dwUserId;
    DWORD dwReserved;
    GUID guid;
} CONFDEST;

Defines a destination node within a conference.

dwSize
The structure size, in bytes.
dwFlags
The destination flags for the transfer. When receiving the CONFN_DATA_SENT or CONFN_DATA_RECEIVED notification, this parameter will be set to one or more of the following:
CONF_DF_BROADCAST Data was broadcast to everyone in the conference.
CONF_DF_PRIVATE Data was sent from one peer 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.
dwUserId
A unique user identification code. If this is zero, it implies everyone in the conference.
dwReserved
Reserved; should be set to zero.
guid
A unique application identifier GUID. The fields of this structure can be set to zero, if not required.

See also ConferenceSendData, ConferenceSendFile, GUID

CONFFILEINFO

typedef struct tagConfFileInfo {
    DWORD dwSize;
    DWORD dwFileId;
    DWORD dwReserved1;
    DWORD dwFileSize;
    DWORD dwReserved2;
    DWORD dwBytesTransferred;
    DWORD dwFileAttributes;
    FILETIME ftCreationTime;
    FILETIME ftLastAccessTime;
    FILETIME ftLastWriteTime;
    TCHAR szFileNameSrc[MAX_PATH];
    TCHAR szFileNameDest[MAX_PATH];
} CONFFILEINFO;

Describes a file in the process of being transferred.

dwSize
The structure size, in bytes.
dwFileId
A unique identifier for the file.
dwReserved1
Reserved; should be set to zero.
dwFileSize
The size of the file, in bytes.
dwReserved2
Reserved; should be set to zero.
dwBytesTransferred
The number of bytes that have been transferred.
dwFileAttributes
The DOS file attributes.
ftCreationTime
The creation time/date of the file.
ftLastAccessTime
The last time/date the file was accessed.
ftLastWriteTime
The last time/date the file was modified.
szFileNameSrc
The original file name.
szFileNameDest
The destination file name. This name is valid only for the receiving process and may not be the same as the original file name.

See also ConferenceCancelTransfer, ConferenceGetInfo, ConferenceSendFile

CONFGUID

typedef struct tagConfGuid {
    DWORD dwSize;
    GUID guid;
    LPCTSTR pszApplication;
    LPCTSTR pszCommandLine;
    LPCTSTR pszDirectory;
} CONFGUID;

Specifies the parameters passed to CreateProcess when an active conference receives a notification to invoke the application associated with the guid.

dwSize
The structure size, in bytes.
guid
The unique application identifier GUID.
pszApplication
Address to a null-terminated string that specifies the module to execute, the full path and file name of the module. If this field is NULL, the module name must be the first white-space-delimited token in the string the pszCommandLine field points to.
pszCommandLine
Address to a null-terminated string that specifies the command line to execute. This field can be NULL. In that case, the function uses the string pointed to by pszApplication as the command line.
pszDirectory
Address to a null-terminated string that specifies the current drive and directory for the process process . The string must be a full path and file name that includes a drive letter. This field can be NULL.

See also ConferenceLaunchRemote, ConferenceSetInfo

CONFINFO

typedef struct tagConfInfo {
    DWORD dwSize;
    HCONF hConf;
    DWORD dwMediaType;
    DWORD dwState;
    DWORD cUsers;
    DWORD dwGCCID;
    TCHAR szConferenceName[CONF_MAX_CONFERENCENAME];
} CONFINFO;

Defines the current conference settings.

dwSize
The structure size, in bytes.
hConf
The handle for the conference.
dwMediaType
The media type for the conference. This can be a combination of one or more of the following:
CONF_MT_ALL Specifies all types.
CONF_MT_AUDIO Audio is available.
CONF_MT_DATA Data conference.
CONF_MT_VIDEO Video is available.
dwState
The current conference state. This can be one of the following:
CONF_CS_ACTIVE The conference is active.
CONF_CS_INITIALIZING The conference is being initialized.
CONF_CS_INVALID This is not a valid state.
CONF_CS_STOPPING The conference is being terminated.
cUsers
The number of users in the conference.
dwGCCID
The GCC conference identifier.
szConferenceName
The null-terminated string representing the name of the conference.

See also ConferenceConnect, ConferenceGetInfo

CONFNOTIFY

typedef struct tagConfNotify {
    DWORD dwSize;
    DWORD dwUser;
    DWORD dwFlags;
    CONFNOTIFYPROC pfnNotifyProc;
    GUID guid;
} CONFNOTIFY;

Specifies the notification callback routine for a process in a conference.

dwSize
The structure size, in bytes.
dwUser
Available for use by the application . This is passed back to the notification callback as the dwUser parameter.
dwFlags
Reserved for future use
pfnNotifyProc
The address of the notification callback routine.
guid
The unique application identifier GUID. A null guid (all zeros) should be used unless the application sends or receives data using the ConferenceSendData function. If a non-zero guid is specified, the callback will receive notifications of incoming data.

An application must fill out the dwSize and pfnNotifyProc fields of this structure.

See also ConferenceConnect, ConferenceGetInfo, ConferenceSendData, CONFNOTIFYPROC

CONFRECDIR

typedef struct tagConfRecDir {
    DWORD dwSize;
    TCHAR szRecDir[MAX_PATH];
} CONFRECDIR;

Describes the default directory for received files.

dwSize
The structure size, in bytes.
szRecDir
The full path of the default directory for received files.

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

See also ConferenceGetInfo, ConferenceSendFile

CONFUSERINFO

typedef struct tagConfUserInfo {
    DWORD dwSize;
    DWORD dwUserId;
    DWORD dwFlags;
    DWORD dwReserved;
    TCHAR szUserName[CONF_MAX_USERNAME];
} CONFUSERINFO;

Describes a single user in a conference.

dwSize
The structure size, in bytes.
dwUserId
A unique value to identify a user within a conference.
dwFlags
Can be a combination of any of the following values:
CONF_UF_AUDIO The user is participating in the audio conference.
CONF_UF_DATA The user is in the data conference.
CONF_UF_LOCAL The user is the local user.
CONF_UF_VIDEO The user is displaying a video image.
dwReserved
Reserved for future use. This must be set to zero.
szUserName
The null-terminated string representing the user's name.

See also ConferenceGetInfo

GUID

 typedef struct _GUID {
    unsigned long Data1;
    unsigned short Data2;
    unsigned short Data3;
    unsigned char Data4[8];
} GUID;

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.

See also CONFDEST, CONFGUID, CONFNOTIFY

HCONF

typedef HANDLE HCONF;

Identifies a conference.

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

HCONFNOTIFY

typedef HANDLE HCONFNOTIFY;

Identifies a conferencing notification callback.

This is returned by the ConferenceSetNotify function to identify a specific callback and must be passed to the ConferenceRemoveNotify function.
Previous Up Index Next

© 1996 Microsoft Corporation