FaxExtRegisterForEvents function (faxext.h)

Article
10/13/2021

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.

Return code	Description
ERROR_INVALID_PARAMETER	At least one parameter passed to the function is invalid.
ERROR_BUSY	The server cannot process a request for notifications while it is sending a notification about a data change. You should try calling the function at a later time.
ERROR_ALREADY_ASSIGNED	The extension has already requested notifications about configuration data changes to this device ID and GUID.
ERROR_NOT_ENOUGH_MEMORY	Not enough memory is available to complete the operation.
ERROR_GEN_FAILURE	An internal failure at the fax server prevents access to the data.
ERROR_SHUTDOWN_IN_PROGRESS	The server is shutting down.

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

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	faxext.h

Share via