PHONE_CREATE message
The TSPI PHONE_CREATE message is sent to the PHONEEVENT callback function to create a new device. This can occur when a new device is detected by Plug and Play, or when a new device is dynamically enabled by the user through a provider configuration function. During the PHONEEVENT callback procedure, TAPI simply queues this message for later processing. When the message is received from the queue, the TSPI_providerCreatePhoneDevice function is called in the context of the TAPISRV process.
PHONE_CREATE
htPhone = (HTAPIPHONE) 0;
dwMsg = (DWORD) PHONE_CREATE;
dwParam1 = (DWORD) hProvider;
dwParam2 = (DWORD) TempDeviceId;
dwParam3 = (DWORD) 0;
Parameters
htPhone
Unused.dwMsg
The value PHONE_CREATE.dwParam1
The service provider handle (hProvider) as received in TSPI_providerEnumDevices.dwParam2
Contains a temporary device identifier generated by the service provider. TAPI uses this value in a subsequent call to TSPI_providerCreatePhoneDevice to assist the provider in associating the message and the function call (in the event that multiple devices are being created).dwParam3
Unused.
Return value
No return value.
Remarks
Service providers can (and should) continue to make static device allocations at startup when TAPI calls TSPI_providerEnumDevices. Creating known devices using this mechanism, instead of always using PHONE_CREATE, involves lower overhead for applications (because they don't have to process PHONE_CREATE messages, updated device information, and so on). The PHONE_CREATE mechanism is intended to be used only if new devices are created while the service provider is active (for example, between TSPI_providerInit and TSPI_providerShutdown).
This message is sent to the PHONEEVENT callback entry point in TAPI. The service provider receives a pointer to this callback in the TSPI_providerEnumDevices function and in each TSPI_phoneOpen function; the PHONE_CREATE message can be sent to the PHONEEVENT callback function given to any open phone or at startup.
Devices cannot be removed dynamically. If a service provider wants to remove a phone from service, it sends a PHONE_STATE (PHONESTATE_DISCONNECTED) message. It can then refuse (for example, by returning PHONEERR_INVALPHONESTATE) to perform any operation with the device until it returns to service or the provider is shut down and restarted (in which case the device could be not declared in TSPI_providerEnumDevices, effectively removing it from the system).
For backward compatibility, older service providers are not expected to send this message. If they do, the message is treated in the same manner as described above for new service providers.
Requirements
TAPI version |
Requires TAPI 2.0 or later |
Header |
Tapi.h |