| Syntax | LONG tapiRequestMediaCall(hWnd, wRequestID, lpszDeviceClass, lpDeviceID, dwSize, dwSecure, lpszDestAddress, lpszAppName, lpszCalledParty, lpszComment) This function allows an application to establish a call that is to carry a media stream that corresponds to the specified device ID of the specified device class. An application would call this operation if it wants a call manager application to establish the call on its behalf. The application is informed about the status of the call via the TAPI_REPLY Windows message. |
| Parameters | HWND hWnd Specifies the application's window handle. This is the window to which TAPI_REPLY messages are sent. hWnd, together with wRequestID also identify the application's call. WORD wRequestID Specifies an application-selected ID that identifies this make call request to the application. This request ID is passed in the wParam field of the TAPI_REPLY message to identify the call to which the message applies. The app must use this request ID when requesting that the call be dropped via tapiRequestDrop. LPCSTR const lpszDeviceClass Specifies a far pointer to a memory location to an ASCII NULL-terminated string where the name of the device class is stored that identifies the media type for the requested call. The device class is really an API identifier (such as "wave" for the the multi-media wave API). The complete list of device classes is to be defined. The maximum length is TAPIMAXDEVICECLASSSIZE bytes, which includes the NULL terminator. Longer strings are truncated. LPCSTR const lpDeviceID Specifies a far pointer to a memory location where the name of the ID for the media device is stored that corresponds to the media stream of the requested call. This device is of the device class specified as lpszDeviceClass. The actual length of the device ID string is dwSize bytes. The maximum length is TAPIMAXDEVICEIDSIZE bytes. Longer strings are truncated. DWORD dwSize Specifies the size in bytes of the device ID string pointed to by lpDeviceID. dwSize must not exceed TAPIMAXDEVICEIDSIZE. DWORD dwSecure Specifies whether or not the requested call is to be established as secure. If zero, the call is not required to be secure and features such as call waiting are not disabled and allowed to interfere with the media stream on the call. If one, the call is required to be secure, if possible. LPCSTR const lpszDestAddress Specifies a far pointer to a memory location where the NULL-terminated destination address of the call request is located. The address can simply be a phone number. It can also use the canonical address format or the dialable address format defined in the Overview chapter. Validity of the specified address is not checked by this operation. The maximum length of the address is TAPIMAXDESTADDRESSSIZE characters, which includes the NULL terminator. Longer strings are truncated. LPCSTR const lpszAppName Specifies a far pointer to a memory location where the ASCII NULL-terminated user-friendly application name of the call request is located. This pointer may be left NULL if the application does not wish to supply an application name. The maximum length of the address is TAPIMAXAPPNAMESIZE characters, which includes the NULL terminator. Longer strings are truncated. LPCSTR const lpszCalledParty Specifies a far pointer to a memory location where the ASCII NULL-terminated user-friendly name for the called party of the call request is located. This pointer may be left NULL if the application does not wish to supply an application name. In that case, the application's module name is used instead. The maximum length of the address is TAPIMAXCALLEDPARTYSIZE characters, which includes the NULL terminator. Longer strings are truncated. LPCSTR const lpszComment Specifies a far pointer to a memory location where the ASCII NULL-terminated comment about the call is located. This pointer may be left NULL if the application does not which to supply a comment. The maximum length of the address is TAPIMAXCOMMENTSIZE characters, which includes the NULL terminator. Longer strings are truncated. |
| Return Value | Returns zero if the request was accepted or a negative error number if an error has occurred. Possible error returns are: TAPIERR_INVALWINDOWHANDLE The specified window handle is invalid. TAPIERR_NOREQUESTRECIPIENT No recipient application is available to handle the request. The user should start the application and try again. TAPIERR_REQUESTQUEUEFULL A recipient application is active, but the request queue is full. The app can try again later. TAPIERR_INVALDESTADDRESS The far pointer to the destination address is NULL. TAPIERR_INVALDEVICECLASS The far pointer to the device class is NULL. TAPIERR_INVALDEVICEID The far pointer to the device ID is NULL. |
| Comments | An telephony-enabled application can request that a media call be placed on its behalf by invoking tapiRequestMediaCall. This request is forwarded to the user's media call control application which establishes the call on behalf of the original application so the media stream identified by the application will become active. A default call control application is provided as part of Windows Telephony. The user can replace this with a call control application of his choice. The media device that the app will use to access the media is identified by its device ID and its corresponding device class. For example, for an audio wave device this may be a small integer device ID and the "wave" device class indication. The format of a device ID is device class dependent. The call manager will attempt to establish a call to carry the media stream that corresponds with the specified media device (if it exists). Note that, depending on the specific media device, it may be necessary for the application to preconfigure the device prior to requesting the establishment of the media call. This will normally require opening the device through the media stream API prior to issuance of the tapiRequestMakeCall. Invoking tapiRequestMakeCall when no call control app is running will return the TAPIERR_REQUESTDENIED error indication. String parameters whose length exceeds the allowed maximum are automatically truncated. |
| See Also | Functions: tapiRequestDrop Messages: TAPI_REQUEST |