INDAdapter::RegisterMemory Method

Article
07/02/2010

Registers an application-defined buffer used for Send, Receive, Read, and Write requests.

Syntax

HRESULT RegisterMemory(
  [in]       const VOID *pBuffer,
  [in]       SIZE_T BufferSize,
  [in, out]  OVERLAPPED *pOverlapped,
  [out]      ND_MR_HANDLE *phMr
);

Parameters

pBuffer [in]
The application-defined buffer to register.
BufferSize [in]
The size, in bytes, of the application-defined buffer.
pOverlapped [in, out]
A pointer to an OVERLAPPED structure that must remain valid for the duration of the operation.
phMr [out]
Opaque handle to the registered memory. The handle is set when the operation completes successfully. If the method returns ND_PENDING, the phMr variable must remain valid until the operation completes.

Return Value

When you implement this method, you should return the following return values. If you return others, try to use well-known values to aid in debugging issues.

Return code	Description
ND_SUCCESS	The operation completed successfully.
ND_PENDING	The Network Direct adapter is in process of registering the memory. Completion is reported asynchronously.
ND_INSUFFICIENT_RESOURCES	There was not enough hardware resources to register the memory.
ND_ACCESS_VIOLATION	The specified buffer or buffer size was not valid.
ND_DEVICE_REMOVED	The underlying Network Direct adapter was removed from the system. Only cleanup operations on the Network Direct adapter will succeed.
ND_INVALID_PARAMETER	The buffer exceeds the size supported by the adapter. For details, see the MaxRegistrationSize member of the ND_ADAPTER_INFO structure.

Remarks

The MaxRegistrationSize member of the ND_ADAPTER_INFO structure contains the maximum application-defined buffer size. To get the adapter information, call the INDAdapter::Query method.

You can allocate and register your memory before connecting, or you can start the connection process and then register the memory before calling INDConnector::Accept or INDConnector::CompleteConnect.

The registered memory's scope is the adapter object. It can be used on any objects within the adapter, for example, multiple endpoints can both use the registered memory. The scope of a memory window is also adapter-wide but it can be bound only to a single endpoint at a time. A window bound to an endpoint cannot be accessed by a different endpoint. However, after being invalidated (unbound), the window could be bound to a different endpoint.

To let a remote peer use the buffer for Read and Write operations, call the INDAdapter::CreateMemoryWindow method to create a memory window. Then, call the INDEndpoint::Bind method to bind the window to the registered memory. The Bind method returns a window descriptor that you send to the remote peer. The remote peer uses the descriptor for Read and Write operations.

Network Direct providers should secure the memory by calling the MmSecureVirtualMemory routine in their kernel drivers as part of memory registration, and calling the MmUnsecureVirtualMemory routine as part of deregistration.

Requirements

Product	Microsoft Message Passing Interface (MS-MPI)
Header	Ndspi.h