Share via

3.3.4.3 NegotiateResources (Opnum 2)

  • Article

The NegotiateResources method is invoked by one partner to request that the other partner allocate resources for future use.

 HRESULT NegotiateResources(
   [in] PCONTEXT_HANDLE phContext,
   [in] RESOURCE_TYPE resourceType,
   [in] DWORD dwcRequested,
   [in, out] DWORD* pdwcAccepted
 );

phContext: An RPC context, returned by a call to BuildContext or BuildContextW, correlated with a session object that is in the Active state. For context handles, see [C706].

resourceType: A RESOURCE_TYPE enumerated value indicating the resource type to be negotiated.

Value

Meaning

RT_CONNECTIONS

0x00

The resource to be negotiated is a connection.

dwcRequested: An unsigned 32-bit integer that specifies the number of resources to allocate. This value MUST be greater than 0x00 and less than 1,000.

pdwcAccepted: A pointer to an unsigned 32-bit integer that receives the number of resources that were allocated on behalf of the caller. This value SHOULD be smaller than the value of dwcRequested if the partner was incapable of allocating all of the requested resources. On input, this value MUST be set to 0x00000000.

Return Values: This method MUST return zero (0x00000000) on success. On failure, it MUST return either one of the values described in the following table of return values or an implementation-specific HRESULT. A client MUST NOT depend on implementation-specific failure HRESULT values. For more information about how the client SHOULD behave based on the possible return values, see section 3.4.6.4. Standard errors are defined in [MS-ERREF] section 2.2.

Return value/code

Description

0x00000000

ERROR_STATUS

The return value indicates success.

0x80000127

E_CM_OUTOFRESOURCES

The server was unable to allocate the resources requested and will continue to operate with the current set of resources.

The following table of return values describes the possible errors that SHOULD be returned by this method.

Return value/code

Description

0x80070057

E_INVALIDARG

This value is returned in the following scenarios:

  • If the resource type that was passed in the resourceType parameter is not a valid resource.

  • If the value of the dwcRequested parameter is not between 1 and 1000.

0x80000123

E_CM_SERVER_NOT_READY

The session object is not in the Active state.

The opnum field value for this method is 2. See [C706].

For the structure and sequence of data on the wire, see [C706] Transfer Syntax Network Data Representation (NDR) topics.

On receiving this method call, the receiving partner MUST verify that the contextHandle parameter is associated with a session object that is in the Active state. For context handles, see [C706]. If the session object is not in the Active state, the partner MUST return from this method with an error code. Otherwise, if the session object is not in the Active state, the server SHOULD return a 0x80000123 (E_CM_SERVER_NOT_READY) error code.

The operation of this method is determined by the level-two protocol that is layered on top of the MSDTC Connection Manager: OleTx Transports Protocol; it is this protocol that defines the range of valid values for the resourceType parameter. If the resourceType parameter does not identify a valid resource, the partner MUST return from this method one of the errors specified on the table above. The server SHOULD return E_INVALIDARG. See [MS-ERREF] section 2.1 for the error code. If the level-two protocol cannot reserve any resources at all, the partner MUST return 0x80000127 (E_CM_OUTOFRESOURCES). Otherwise, if at least one resource is allocated, the partner MUST set the pdwcAccepted parameter to the number of resources allocated by this request, and then return S_OK.