3.1.4.1.28 FAX_EnumPorts (Opnum 10)

The FAX_EnumPorts (Opnum 10) method is called by the client to obtain port state information.

In response, the server MUST validate whether the client's fax user account has access to enumerate all the devices (ports) on the server. On success, the server MUST return information about all its devices in PortBuffer. It MUST also return the size of the returned information and the number of devices for which it successfully enumerated information.

The client SHOULD free the returned buffer.

 error_status_t FAX_EnumPorts(
   [in] handle_t hBinding,
   [out, size_is(,*BufferSize)] LPBYTE* PortBuffer,
   [out, ref] LPDWORD BufferSize,
   [out, ref] LPDWORD PortsReturned
 );

hBinding: 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.

PortBuffer: A pointer to the address of a buffer to receive an array of _FAX_PORT_INFO (section 2.2.8) structures. Each structure describes one fax port.

BufferSize: A variable to return the size, in bytes, of the port buffer.

PortsReturned: A pointer to a DWORD ([MS-DTYP] section 2.2.9) variable to receive the number of _FAX_PORT_INFO that the method returns in the PortBuffer parameter.

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 access rights (FAX_ACCESS_QUERY_CONFIG) required for this operation.
ERROR_NOT_ENOUGH_MEMORY 0x00000008	Not enough storage is available to process this command. The fax server cannot allocate sufficient memory to hold the array of _FAX_PORT_INFO to be returned to the client.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error code is returned if any of the following conditions are met:<95> § The PortBuffer parameter is set to a NULL pointer value. § The PortsReturned parameter is set to a NULL pointer value.
ERROR_INTERNAL_ERROR 0x0000054F	The fax server failed to custom marshal the array of _FAX_PORT_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].