2.3 NDIS Library Functions Used by Protocol Drivers

In addition to the NdisXxx listed here, highest-level NDIS protocol drivers that are Windows NT transport protocols call the TdiXxx functions described later in Part II.

NdisAcquireSpinLock

Acquires a spin lock so the caller can synchronize access to resources shared among nonISR driver routines in a multiprocessor-safe way.

NdisAdjustBufferLength

Modifies the length specified in a given buffer descriptor that was allocated or copied by the caller.

NdisAllocateBuffer

Creates a buffer descriptor describing a specified virtual (sub)range within an already allocated, nonpaged memory block, given a handle returned by NdisAllocateBufferPool or NdisAllocateMemory.

NdisAllocateBufferPool

Returns a handle with which the caller can allocate buffer descriptors with NdisAllocateBuffer.

NdisAllocateMemory

Allocates resident (nonpaged) system-space memory, optionally within a specified address limit, as a physically contiguous allocation, and/or as a noncached allocation.

NdisAllocatePacket

Allocates a packet descriptor, given a handle returned by a preceding call to NdisAllocatePacketPool.

NdisAllocatePacketPool

Allocates and initializes a block of nonpaged packet pool, given the number of packet descriptors and how many bytes each fixed-size packet descriptor should contain.

NdisAllocateSpinLock

Initializes a variable of type NDIS_SPIN_LOCK, used to synchronize access to data shared among driver routines. An initialized spin lock, for which the caller supplies resident storage, is a required parameter to the Ndis..SpinLock and NdisInterlockedXxx functions.

NdisAnsiStringToUnicodeString

Converts a given counted ANSI string into a counted Unicode string.

NDIS_BUFFER_LINKAGE

Returns a pointer to a linked buffer, given a pointer to an NDIS buffer descriptor.

NdisChainBufferAtBack

Links a given buffer descriptor at the end of the chain of buffer descriptors for a given packet descriptor.

NdisChainBufferAtFront

Links a given buffer descriptor at the start of the chain of buffer descriptors for a given packet descriptor.

NdisCloseAdapter

Releases the binding set up with NdisOpenAdapter, given the binding handle that it previously returned.

NdisCloseConfiguration

Releases the handle returned by NdisOpenProtocolConfiguration after the caller has retrieved configuration information and/or, possibly, stored additional information about itself in the registry.

NdisCompleteBindAdapter

Completes a binding operation when the driver returned NDIS_STATUS_PENDING from its ProtocolBindAdapter function.

NdisCompleteUnbindAdapter

Completes a close-adapter operation when the driver returned NDIS_STATUS_PENDING from its ProtocolUnbindAdapter function.

NdisCopyBuffer

Creates a buffer descriptor for a specified virtual (sub)range, given a handle for a block of already allocated memory and a pointer to the memory descriptor for the block.

NdisCopyFromPacketToPacket

Copies a specified number of bytes of data from one packet to another, starting at a specified offset in a given source packet's data and copying the data to a specified offset in the target packet. Returns the number of bytes actually copied, which can be less than the requested number, depending on the source packet and specified starting offset for the copy operation.

NdisDeregisterProtocol

Releases the resources allocated when the driver called NdisRegisterProtocol, given the protocol handle it returned at initialization.

NdisDprAllocatePacket

Allocates and initializes a packet descriptor when the caller is running at IRQL DISPATCH_LEVEL, given a handle returned by a preceding call to NdisAllocatePacketPool.

NdisDprAllocatePacketNonInterlocked

Allocates a packet descriptor when the caller is running at IRQL DISPATCH_LEVEL and that caller provides internal synchronization for accessing packet pool, given a handle returned by a preceding call to NdisAllocatePacketPool.

NdisDprFreePacket

Releases a driver-allocated packet descriptor and returns it to the free list when the caller is running at IRQL DISPATCH_LEVEL.

NdisDprFreePacketNonInterlocked

Releases a packet descriptor that was allocated with NdisDprAllocatePacketNonInterlocked and returns it to the free list.

NdisEqualString

Compares two strings to determine whether they are equal.

NdisFreeBuffer

Releases a buffer descriptor obtained in a preceding call to NdisAllocateBuffer or NdisCopyBuffer.

NdisFreeBufferPool

Releases a handle obtained in a preceding call to NdisAllocateBufferPool.

NdisFreeMemory

Releases a handle that was obtained in a preceding call to NdisAllocateMemory.

NdisFreePacket

Releases a packet descriptor that was allocated from packet pool with NdisAllocatePacket and returns it to the free list.

NdisFreePacketPool

Releases a handle to a block of packet pool that was allocated with NdisAllocatePacketPool.

NdisFreeSpinLock

Releases a spin lock initialized in a preceding call to NdisAllocateSpinLock, usually when a driver is unloading.

NdisFreeString

Frees the storage for a buffered string.

NdisGetBufferPhysicalArraySize

Returns the number of physical discontiguities in a buffer, given the buffer descriptor.

NdisGetCurrentProcessorCpuUsage

Returns how busy the current processor is as a percentage.

NdisGetCurrentSystemTime

Returns the current system time, suitable for use as a timestamp.

NdisGetFirstBufferFromPacket

Returns pointers to the buffer descriptor and base virtual address for the initial buffer chained to a given packet, along with the sizes of the initial buffer and full buffer, in case the buffer is fragmented.

NdisGetNextBuffer

Returns the next buffer descriptor in a chain, given the current buffer descriptor.

NdisGetPacketFlags

Returns the flags, if any, set by a higher-level protocol driver in a given packet.

NDIS_GET_PACKET_HEADER_SIZE

Returns the number of bytes in a received net packet header from the HeaderSize set in the NDIS_PACKET_OOB_DATA block associated with a given packet descriptor by the indicating miniport.

NDIS_GET_PACKET_MEDIA_SPECIFIC_INFO

Returns a pointer to buffered out-of-band information, such as packet priority, and the number of bytes in the buffer from the MediaSpecificInformation and SizeMediaSpecificInfo set in the NDIS_PACKET_OOB_DATA block associated with a given packet descriptor by the indicating miniport.

NDIS_GET_PACKET_TIME_RECEIVED

Returns the TimeReceived timestamp from the NDIS_PACKET_OOB_DATA block associated with an indicated receive packet.

NDIS_GET_PACKET_TIME_SENT

Returns the TimeSent timestamp from the associated NDIS_PACKET_OOB_DATA block associated with an indicated receive packet.

NdisIMDeInitializeDeviceInstance

Calls an NDIS intermediate driver's MiniportHalt function to tear down the driver's virtual NIC.

NdisIMInitializeDeviceInstance

Calls an NDIS intermediate driver's MiniportInitialize function to set up the driver's virtual NIC for I/O operations bound for an underlying NIC driver to which the intermediate driver is bound.

NdisIMQueueMiniportCallback

Calls an intermediate driver's callback function to when it can execute in a MiniportXxx context, as, for example, to forward an indication to higher-level protocols.

NdisIMRegisterLayeredMiniport

Registers an NDIS intermediate driver's MiniportXxx entry points and name with the NDIS library when the driver initializes.

NdisIMRevertBack

Returns the function of an intermediate driver to the context in which it was executing before it called NdisIMSwitchToMiniport.

NdisIMSwitchToMiniport

Allows an intermediate driver function to call NdisMXxx normally called only from MiniportXxx functions, as, for example, to make indications up to higher-level protocols.

NdisInitAnsiString

Initializes a counted ANSI string.

NDIS_INIT_FUNCTION

Marks a given driver function as initialization-only code to be discarded after the function has run once.

NdisInitializeEvent

Sets up an event object during driver initialization to be used subsequently as a synchronization mechanism.

NdisInitializeListHead

Sets up a queue header for a driver's internal queue, given a pointer to driver-supplied resident storage for the queue header and queue. Then, entries (usually packets) can be added to and removed from the doubly-linked queue with the NdisInterlocked..List functions.

NdisInitializeString

Allocates a buffer for and initializes a counted string in the system-default character set, given a source string and a NULL pointer.

NdisInitUnicodeString

Initializes a counted Unicode string.

NdisInterlockedAddUlong

Adds an unsigned long value to a given unsigned integer as an atomic operation, using a caller-supplied and initialized spin lock.

NdisInterlockedInsertHeadList

Inserts an entry, usually a packet, at the head of a doubly linked list using a caller-supplied and initialized spin lock so that access to queued entries is synchronized in a multiprocessor-safe way among driver functions.

NdisInterlockedInsertTailList

Inserts an entry, usually a packet, at the end of a doubly linked list using a caller-supplied and initialized spin lock so that access to queued entries is synchronized in a multiprocessor-safe way among driver functions.

NdisInterlockedRemoveHeadList

Removes an entry, usually a packet, from the head of a doubly linked list using a caller-supplied and initialized spin lock so that access to queued entries is synchronized in a multiprocessor-safe way among driver functions.

NdisMoveMemory

Copies a specified number of bytes from one caller-supplied location to another.

NdisMSetAttributesEx

Informs the NDIS library about significant features of an intermediate driver's virtual NIC and prevents NDIS from timing out sends and requests in the intermediate driver.

NDIS_OOB_DATA_FROM_PACKET

Returns a pointer to the NDIS_PACKET_OOB_DATA block associated with a given packet descriptor.

NdisOpenAdapter

Sets up a binding between the caller and an underlying NIC driver, given an array of medium types that the protocol driver supports, the number of elements in the supplied array, the handle already returned by NdisRegisterProtocol, a handle to a protocol-supplied context area to be passed back to the protocol in subsequent receive indications, the name of the NIC to be opened, a mask set with the caller's preferred open options, and, possibly, a pointer to some caller-supplied addressing information, as well as four caller-specified locations at which NdisOpenAdapter returns values. If the call succeeds, NdisOpenAdapter returns a binding handle for the protocol to use in subsequent NdisXxx calls that forward device I/O requests to the NIC driver, an index specifying the NIC driver's preferred medium type, and NDIS_STATUS_SUCCESS; otherwise, it returns both a general failure status and an informational error status.

NdisOpenProtocolConfiguration

Returns a handle for a driver's HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services
\
NICDriverInstance\Parameters\ProtocolName registry key. This handle is a required parameter to other NdisXxx configuration functions.

NDIS_PAGABLE_FUNCTION

Marks a driver function as pageable code.

NdisPrintString

Displays a given string in the debugging window.

NdisQueryBuffer

Retrieves the size of the range, and optionally its base virtual address, specified in a given buffer descriptor.

NdisQueryBufferOffset

Retrieves the base virtual address of the range specified in a given buffer descriptor.

NdisQueryPacket

Returns any or all of the following information about a given packet descriptor: a count of buffer descriptors chained to the packet descriptor, the total number of bytes in all buffers mapped by the buffer descriptor chained to the packet descriptor, the total number of physically discontiguous blocks for all such buffers, and a pointer to the initial buffer descriptor in the chain.

NdisQueryReceiveInformation

Returns information from the out-of-band data block associated with a given packet descriptor set up by the underlying driver for a receive indication.

NdisReadConfiguration

Reads the value of a named entry of the specified type, given the registry handle for the ..\Parameters\ProtocolName key returned by NdisOpenProtocolConfiguration.

NdisRecalculatePacketCounts

Resets the valid counts of chained buffer descriptors for a given packet descriptor.

NdisRegisterProtocol

Registers a protocol driver's upper-edge entry points (ProtocolXxx) and name with the NDIS library, given a pointer to the NDIS_PROTOCOL_CHARACTERISTICS structure set up by the caller and the size in bytes of this structure. NDIS returns the status of the registration attempt and, if the call is successful, a protocol handle representing the driver, which can be passed in a subsequent call to NdisOpenAdapter.

NdisReinitializePacket

Sets to NULL the queue head for any chained buffers in a given packet descriptor and reinitializes it for reuse.

NdisReleaseSpinLock

Releases a spin lock that was acquired in a preceding call to NdisAcquireSpinLock.

NdisRequest

Forwards a caller-initialized NDIS_REQUEST-type query or set request to the underlying NIC driver, given the binding handle previously returned by NdisOpenAdapter.

NdisReset

Forwards a reset request to the underlying NIC driver, given the binding handle and a pointer to a variable in which the status of the reset operation is returned.

NdisResetEvent

Clears the Signaled state of a given event.

NdisRetrieveUlong

Retrieves a ULONG value from the source address, avoiding alignment faults.

NdisReturnPackets

Releases ownership of one or more receive packets after a protocol driver has consumed the receive data.

NdisSend

Forwards a packet to the NIC driver for transmission over the wire, given the binding handle, a pointer to the packet to be sent, and a pointer to a variable in which the status of the send is returned.

NdisSendPackets

Forwards a multipacket send request, possibly specifying out-of-band information for each packet in the array, such as packet priority, to the underlying driver.

NdisSetEvent

Sets a given event to the Signaled state if it was not already Signaled, thereby causing waits on the event to be satisfied.

NdisSetPacketFlags

Sets the Flags member in a given packet descriptor to the given value, before the protocol calls NdisSendPackets or NdisSend.

NDIS_SET_PACKET_MEDIA_SPECIFIC_INFO

Sets the MediaSpecificInformation and SizeMediaSpecificInfo in the NDIS_PACKET_OOB_DATA block, specifying out-of-band information associated with a protocol-allocated packet descriptor for a send request.

NDIS_SET_PACKET_TIME_TO_SEND

Sets the TimeToSend timestamp in the NDIS_PACKET_OOB_DATA block associated with a protocol-allocated packet descriptor, specifying when the underlying driver should transmit the packet data over the wire.

NdisSetSendFlags

See NdisSetPacketFlags.

NdisStoreUlong

Stores a ULONG value at a particular address, avoiding alignment faults.

NdisTransferData

Forwards a request that the underlying NIC driver transfer (copy) received data to a supplied packet, given the binding handle, the receive-context handle passed to the protocol when the receive was indicated, the byte offset in the indication at which to start the transfer and the number of bytes to transfer, and pointers to variables in which the status of the completed transfer operation and the number of bytes actually transferred are returned.

NdisUnchainBufferAtBack

Removes a given buffer descriptor at the end of the chain of buffer descriptors for a given packet descriptor and returns a pointer to the buffer descriptor.

NdisUnchainBufferAtFront

Removes a given buffer descriptor at the start of the chain of buffer descriptors for a given packet descriptor and returns a pointer to the buffer descriptor.

NdisUnicodeStringToAnsiString

Converts a given counted Unicode string into a counted ANSI string.

NdisWaitEvent

Puts the caller into a wait state until the given event is set to the Signaled state or the wait times out.

NdisWriteConfiguration

Writes a caller-supplied value entry in the registry, given the handle for the ..\Parameters\ProtocolName key returned by NdisOpenProtocolConfiguration.

NdisWriteErrorLogEntry

Allocates an error-log record, fills it in, and writes it to the I/O error log, given a binding handle for the underlying NIC, an NDIS_XXX error code, a count of caller-supplied error values, and a corresponding number of ULONGs specifying additional information about the I/O error or configuration error.

NdisZeroMemory

Fills a block of memory with zeros, given a pointer to the block and the length in bytes to be filled.

Highest-level NDIS drivers that export only the lower-edge ProtocolXxx functions also can call support routines exported by other Windows NT kernel-mode components. For more information about these support routines, see the Kernel-Mode Driver Reference.