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.