3.1.4.2.16 FaxObs_GetPort (Opnum 14)

The FaxObs_GetPort (Opnum 14) method is called by the client to retrieve status information from the server about the specified fax port (device).

The server MUST validate that the client's fax user account has the access to get port (device) status information. The client MUST set the FaxPortHandle parameter to a valid fax port handle value returned by the FaxObs_OpenPort (section 3.1.4.2.5) method. On success, the server MUST return information for the specified fax port in PortBuffer.

The client SHOULD free the returned buffer.

 error_status_t FaxObs_GetPort(
   [in] RPC_FAX_PORT_HANDLE FaxPortHandle,
   [in, out, unique, size_is(,*BufferSize)] 
     LPBYTE* PortBuffer,
   [in, out] LPDWORD BufferSize
 );

FaxPortHandle: An RPC context handle that references a fax port.

PortBuffer: A pointer to the address of the returned buffer containing a _FAX_PORT_INFO (section 2.2.8) structure. The structure describes one fax port (device).

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

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 _FAX_PORT_INFO to be returned to the client.

ERROR_INVALID_DATA

0x0000000D

This error SHOULD be returned if the FaxPortHandle argument is not a valid handle obtained using FaxObs_OpenPort.<200>

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