RIORegisterBuffer function
The RIORegisterBuffer function registers a RIO_BUFFERID, a registered buffer descriptor, with a specified buffer for use with the Winsock registered I/O extensions.
Syntax
RIO_BUFFERID RIORegisterBuffer(
_In_ PCHAR DataBuffer,
_In_ DWORD DataLength
);
Parameters
DataBuffer [in]
A pointer to the beginning of the memory buffer to register.DataLength [in]
The length, in bytes, in the buffer to register.
Return value
If no error occurs, the RIORegisterBuffer function returns a registered buffer descriptor. Otherwise, a value of RIO_INVALID_BUFFERID is returned, and a specific error code can be retrieved by calling the WSAGetLastError function.
| Return code | Description |
|---|---|
| WSAEFAULT | The system detected an invalid pointer address in attempting to use a pointer argument in a call. This error is returned if an invalid buffer pointer is passed in DataBuffer parameter. |
| WSAEINVAL | An invalid parameter was passed to the function. This error is returned if the DataLength parameter is zero. |
Remarks
The RIORegisterBuffer function creates a registered buffer identifier for a specified buffer. When a buffer is registered, the virtual memory pages containing the buffer will be locked into physical memory.
If several small, non-contiguous buffers are registered, the physical memory footprint for the buffers may effectively be as large as an entire memory page per registration. In these cases it may be beneficial to allocate multiple request buffers together.
There is also a small amount of overhead in physical memory used for the buffer registration itself. So if there are many allocations aggregated into single larger allocation, the physical memory footprint may be reduced further by aggregating the buffer registrations as well. In this case the application may need to take extra care to ensure that the buffers are eventually deregistered, but not while any send or receive requests are outstanding.
A portion of a registered buffer is passed to the RIOSend, RIOSendEx, RIOReceive, and RIOReceiveEx functions in the pData parameter for sending or receiving data.
When the buffer identifier is no longer needed, call the RIODeregisterBuffer function to deregister the buffer identifier.
Note The function pointer to the RIORegisterBuffer function must be obtained at run time by making a call to the WSAIoctl function with the SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER opcode specified. The input buffer passed to the WSAIoctl function must contain WSAID_MULTIPLE_RIO, a globally unique identifier (GUID) whose value identifies the Winsock registered I/O extension functions. On success, the output returned by the WSAIoctl function contains a pointer to the RIO_EXTENSION_FUNCTION_TABLE structure that contains pointers to the Winsock registered I/O extension functions. The SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER IOCTL is defined in the Ws2def.h header file. The WSAID_MULTIPLE_RIO GUID is defined in the Mswsock.h header file.
Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.
Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows Server 2012 R2, and later.
Requirements
Minimum supported client |
Windows 8.1, Windows 8 [desktop apps | UWP apps] |
Minimum supported server |
Windows Server 2012 [desktop apps | UWP apps] |
Minimum supported phone |
Windows Phone 8 |
Header |
Mswsock.h |
Library |
Mswsock.lib |
DLL |
Mswsock.dll |