FaxExtGetData function (faxext.h)

The FaxExtGetData callback function retrieves configuration data for a specific device and GUID.

Syntax

DWORD FaxExtGetData(
  [in]  DWORD                     dwDeviceId,
  [in]  FAX_ENUM_DEVICE_ID_SOURCE DevIdSrc,
  [in]  LPCWSTR                   lpcwstrDataGUID,
  [out] LPBYTE                    *ppData,
  [out] LPDWORD                   lpdwDataSize
);

Parameters

[in] dwDeviceId

Type: DWORD

Specifies a DWORD value that indicates the device for which data is to be retrieved.

If this parameter is zero, it indicates that the data to retrieve 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 retrieve; for example, "{b8959fc9-4e77-4ee9-8411-009acb1bbf3e}".

[out] ppData

Type: LPBYTE*

Pointer to a buffer to receive the configuration data. The fax service allocates the memory for the buffer. The fax service regards this data as an opaque collection of bits. The service stores and reads the named data but does not manipulate the data.

[out] lpdwDataSize

Type: LPDWORD

Pointer to a DWORD value that indicates the size, in bytes, of the data returned in the ppData 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 FaxExtGetData 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.

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

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

Requirements

See also

FaxExtFreeBuffer

FaxExtInitializeConfig

FaxExtSetData