3.1.4.2.28 FaxObs_GetTapiLocations (Opnum 26)

The FaxObs_GetTapiLocations (Opnum 26) method is called by the client to retrieve the current and other available TAPI locations configured for the server. The TAPI locations can be set by the client with the FaxObs_SetTapiLocations (section 3.1.4.2.29) method.

A TAPI location is described by a FAX_TAPI_LOCATIONS (section 2.2.88) data structure, which includes information such as a friendly name, country code, and area code for the respective location. For more information about TAPI see [MSDN-TAPI2.2].

On success, the server MUST allocate memory for and return the data describing its current and other available TAPI locations.

The client SHOULD free the buffer.

 error_status_t FaxObs_GetTapiLocations(
   [in] handle_t hBinding,
   [in, out, unique, size_is(,*BufferSize)] 
     LPBYTE* Buffer,
   [in, out] LPDWORD BufferSize
 );

hBinding: A handle that is provided by the client RPC layer when the RPC call is made.

Buffer: A pointer to the address of the returned buffer containing a FAX_TAPI_LOCATION_INFO (section 2.2.89) structure that contains a list of FAX_TAPI_LOCATIONS, each FAX_TAPI_LOCATIONS describes one location. Each structure includes information such as a friendly name, country code, and area code. The current location can be identified in this list of FAX_TAPI_LOCATIONS by searching for a structure with the location identifier value (contained by the PermanentLocationID member) described by the CurrentLocationID member of the FAX_TAPI_LOCATION_INFO.

BufferSize: Pointer to a DWORD ([MS-DTYP] section 2.2.9) variable that receives the size, in bytes, of the data returned in the 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_CONFIG_QUERY access rights.
ERROR_NOT_ENOUGH_MEMORY 0x00000008	The fax server cannot allocate sufficient memory to hold the data to be returned to the client.
ERROR_INVALID_PARAMETER 0x00000057	The parameter is incorrect. This error is returned if any of the following parameters are set to a NULL pointer value: Buffer or BufferSize.<211>

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