3.1.4.1.19 FAX_EnumerateProviders (Opnum 45)

The FAX_EnumerateProviders (Opnum 45) method is called by the client to enumerate all the FSPs installed on the server.

The server MUST validate that the client's fax user account has access to enumerate providers. The Buffer parameter MUST NOT be NULL. On success, the server MUST return the FSPs installed on the fax server.

The client SHOULD free the returned buffer.

 error_status_t FAX_EnumerateProviders(
   [in] handle_t hFaxHandle,
   [out, size_is(, *BufferSize)] LPBYTE* Buffer,
   [out, ref] LPDWORD BufferSize,
   [out, ref] LPDWORD lpdwNumProviders
 );

hFaxHandle: The RPC binding handle for this call. The client SHOULD reuse the RPC binding handle used as an input hBinding argument for the FAX_ConnectFaxServer (section 3.1.4.1.10) or FAX_ConnectionRefCount (section 3.1.4.1.11) method call used to connect to the fax server.

Buffer: A pointer to the address of a buffer to receive an array of FAX_DEVICE_PROVIDER_INFO (section 2.2.30) structures. Each structure contains information about one fax device provider, as it pertains to the entire fax service.

BufferSize: A pointer to a DWORD ([MS-DTYP] section 2.2.9) in which to return the size, in bytes, of the buffer.

lpdwNumProviders: A pointer to a DWORD variable to receive the number of FAX_DEVICE_PROVIDER_INFO that the method returns in Buffer. This number MUST be equal to the total number of FSPs installed on the target server.

Return Values: This method MUST return 0x00000000 (ERROR_SUCCESS) for success; otherwise, it MUST return one of the following error codes, one of the fax-specific errors that are defined in section 2.2.52, or one of the other standard errors defined in [MS-ERREF] section 2.2.

Return value/code	Description
ERROR_ACCESS_DENIED 0x00000005	Access is denied. The client's fax user account does not have the FAX_ACCESS_QUERY_CONFIG access rights required for this operation.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error is returned if the BufferSize and/or the lpdwNumProviders parameters are set to NULL pointer values.
ERROR_INTERNAL_ERROR 0x0000054F	The fax server failed to custom marshal the array of FAX_DEVICE_PROVIDER_INFO structures to be returned to the client.
FAX_ERR_SRV_OUTOFMEMORY 0x00001B59	The fax server failed to allocate sufficient memory for the return buffer to hold the FAX_DEVICE_PROVIDER_INFO to be returned to the client.

Exceptions Thrown: No exceptions are thrown except those that are thrown by the underlying RPC protocol, [MS-RPCE].