3.1.4.2.15 FaxObs_EnumPorts (Opnum 13)

The FaxObs_EnumPorts (Opnum 13) method is called by the client to enumerate the fax ports (devices) on the server and retrieve information describing these ports (devices).

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

The client SHOULD free the returned buffer.

 error_status_t FaxObs_EnumPorts(
   [in] handle_t hBinding,
   [in, out, unique, size_is(,*BufferSize)] 
     LPBYTE* PortBuffer,
   [in, out] LPDWORD BufferSize,
   [out] 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 FaxObs_ConnectionRefCount (section 3.1.4.2.2) method call used to connect to the fax server.

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

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

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 FAX_ PORT_QUERY access rights.

ERROR_NOT_ENOUGH_MEMORY

0x00000008

The fax server cannot allocate sufficient memory to hold the array of _FAX_PORT_INFO structures to be returned to the client.

ERROR_INVALID_PARAMETER

0x00000057

The PortsReturned parameter is set to a NULL pointer value.<199>

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