FaxExtRegisterForEvents function (faxext.h)

The FaxExtRegisterForEvents callback function registers the fax extension DLL for notifications about configuration data changes related to a specific device and GUID.

Syntax

HANDLE FaxExtRegisterForEvents(
  [in] HINSTANCE                 hInst,
  [in] DWORD                     dwDeviceId,
  [in] FAX_ENUM_DEVICE_ID_SOURCE DevIdSrc,
  [in] LPCWSTR                   lpcwstrDataGUID,
  [in] PFAX_EXT_CONFIG_CHANGE    lpConfigChangeCallback
);

Parameters

[in] hInst

Type: HINSTANCE

Specifies an HINSTANCE value that identifies the fax extension DLL instance that is requesting notifications. The fax service uses this value to prevent sending notifications about data changes to the same extension that changed the data.

[in] dwDeviceId

Type: DWORD

Specifies a DWORD value that indicates the device for which notifications should be sent.

This parameter can be zero, indicating that the fax service should send notifications about changes to global configuration data, which is configuration data that is not associated with a specific device. For more information, see Storing Global Configuration Data.

[in] DevIdSrc

Type: FAX_ENUM_DEVICE_ID_SOURCE

Specifies the source of the dwDeviceId parameter. This parameter can have one of the following values.

DEV_ID_SRC_FAX (DEV_ID_SRC_FAX)

The dwDeviceId parameter is generated by the fax service or by a virtual FSP. Fax routing extensions and virtual FSPs should use this value.

DEV_ID_SRC_TAPI (DEV_ID_SRC_TAPI)

The dwDeviceId parameter is generated by a TAPI TSP. FSPs that are TAPI-based should use this value.

[in] lpcwstrDataGUID

Type: LPCWSTR

Pointer to a constant null-terminated Unicode character string that specifies the GUID of the data for which notifications should be sent; for example, "{b8959fc9-4e77-4ee9-8411-009acb1bbf3e}".

[in] lpConfigChangeCallback

Type: LPBYTE

Pointer to a FaxExtConfigChange callback function defined in the fax extension DLL. The fax service calls this function to notify the fax extension about configuration data changes.

Return value

Type: HANDLE

If the function succeeds, the return value is a notification HANDLE.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

The FaxExtRegisterForEvents function can return the following error codes.

Remarks

When the fax extension calls this fax service callback function, it must use the function pointer exposed by the fax service when the service calls the FaxExtInitializeConfig function.

Security requirements: The caller must have access rights to query a server's configuration in order to call this function.

If an extension registers to receive notifications about configuration data changes, the extension does not receive notifications about new configuration values that it sets itself.

A fax extension can register to receive notifications about data changes that occur for device IDs and GUIDs that will exist at a later time. Once the device ID and GUID receive data, the fax service issues the change notification. It is also possible to store configuration data (that is, call the FaxExtSetData function) for devices that do not yet exist.

The fax service passes a pointer to the FaxExtRegisterForEvents callback function when the fax service calls the FaxExtInitializeConfig function. The PFAX_EXT_REGISTER_FOR_EVENTS data type is a pointer to a FaxExtRegisterForEvents function.

The FaxExtUnregisterForEvents callback function unregisters the fax extension DLL for notifications about global configuration data changes or configuration data changes related to a specific device and GUID.

Applications can change global configuration data or the data associated with a specific fax device by calling the FaxExtSetData function.

Requirements

See also

FaxExtConfigChange

FaxExtInitializeConfig

FaxExtSetData

FaxExtUnregisterForEvents