NDIS_STATUS
NdisMCreateLog(
IN NDIS_HANDLE MiniportAdapterHandle,
IN UINT Size,
OUT PNDIS_HANDLE LogHandle
);
NdisMCreateLog allocates and opens a log file in which a NIC miniport can write data to be displayed by a driver-dedicated Win32 application.
Parameters
MiniportAdapterHandle
Specifies the handle input to MiniportInitialize.
Size
Specifies how many bytes to allocate for the log file. NDIS creates a temporary file that is not stored on disk.
LogHandle
Points to a caller-supplied variable in which this function returns a handle to the log file. This handle is a required parameter to the Ndis..Log functions that the miniport calls subsequently.
Return Value
NdisMCreateLog can return one of the following:
NDIS_STATUS_SUCCESS
The miniport can use the handle returned at LogHandle to write data to the NDIS-allocated log file.
NDIS_STATUS_RESOURCES
A log file of the specified size could not be allocated.
NDIS_STATUS_FAILURE
The driver already called NdisMCreateLog successfully.
Comments
A NIC miniport can call the NdisM..Log functions to provide any information the driver writer chooses. Whatever the miniport logs can be displayed by a driver-dedicated Win32 application. Such an application calls the Win32 function DeviceIoControl with IOCTL_NDIS_GET_LOG_DATA periodically to retrieve whatever the miniport has written to the log file. For example, an under-development miniport might write test data to be displayed by its corresponding application.
If NdisMCreateLog returns NDIS_STATUS_RESOURCES, the driver can adjust the original Size down and try calling this function again. However, a miniport cannot call NdisMCreateLog to create more than one log file after a call succeeds.
Whatever size of log file is allocated, subsequent calls to NdisMWriteLogData store data in this file, which is treated as a circular buffer. That is, a sequence of calls to NdisMWriteLogData eventually overwrites the data originally written to the log file.
Callers of NdisMCreateLog run at IRQL PASSIVE_LEVEL.
See Also
MiniportInitialize, NdisMCloseLog, NdisMFlushLog, NdisMWriteLogData