Edit

Share via

FaxExtSetData function (faxext.h)

  • Article

The FaxExtSetData function sets configuration data for a specific device and GUID.

Syntax

DWORD FaxExtSetData(
  [in] HINSTANCE                 hInst,
  [in] DWORD                     dwDeviceId,
  [in] FAX_ENUM_DEVICE_ID_SOURCE DevIdSrc,
  [in] LPCWSTR                   lpcwstrDataGUID,
  [in] LPBYTE                    pData,
  [in] DWORD                     dwDataSize
);

Parameters

[in] hInst

Type: HINSTANCE

Specifies an HINSTANCE value that identifies the fax extension DLL instance that is requesting a data change. 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 data is to be set.

If this parameter is zero, it indicates that the data to set is global configuration data (configuration data that is not associated with a specific device). For example, a fax routing extension may export several different fax routing methods that use OCR technology and rely on the same OCR parameters. The routing extension can specify that the OCR configuration data is global, rather than device-specific, by specifying zero in this parameter. 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 to set; for example, "{b8959fc9-4e77-4ee9-8411-009acb1bbf3e}".

[in] pData

Type: LPBYTE

Pointer to the buffer that contains the configuration data to set.

[in] dwDataSize

Type: DWORD

A DWORD value that indicates the size, in bytes, of the buffer pointed to by the pData parameter.

Return value

Type: DWORD

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in WinError.h. You can call the Win32 FormatMessage function specifying the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a generic description of the error.

The FaxExtSetData function can return the following error codes.

Return code Description
ERROR_SUCCESS
 The configuration data was successfully stored.
ERROR_INVALID_PARAMETER
 At least one parameter passed to the function is invalid.
ERROR_NOT_ENOUGH_MEMORY
 Not enough memory is available to complete the operation.
ERROR_FILE_NOT_FOUND
 A device with the specified device ID was not found.
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 manage server configuration data in order to call this function.

You can call the FaxExtGetData function to retrieve global configuration data or configuration data for a specific device and GUID.

The fax service passes a pointer to the FaxExtSetData callback function when the fax service calls the FaxExtInitializeConfig function. The PFAX_EXT_SET_DATA data type is a pointer to a 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

See also

FaxExtGetData

FaxExtInitializeConfig