packet.h

ddk wizard demo for vc programe

			IN PIRP Irp
			);


/*!
  \brief Writes a buffer of raw packets to the network.
  \param Irp Pointer to the IRP containing the user request.
  \param UserBuff Pointer to the buffer containing the packets to send.
  \param UserBuffSize Size of the buffer with the packets.
  \return The amount of bytes actually sent. If the return value is smaller than the Size parameter, an
          error occurred during the send. The error can be caused by an adapter problem or by an
		  inconsistent/bogus user buffer.

  This function is called by the OS in consequence of a BIOCSENDPACKETSNOSYNC or a BIOCSENDPACKETSSYNC IOCTL.
  The buffer received as input parameter contains an arbitrary number of packets, each of which preceded by a
  sf_pkthdr structure. NPF_BufferedWrite() scans the buffer and sends every packet via the NdisSend() function.
  When Sync is set to TRUE, the packets are synchronized with the KeQueryPerformanceCounter() function.
  This requires a remarkable amount of CPU, but allows to respect the timestamps associated with packets with a precision 
  of some microseconds (depending on the precision of the performance counter of the machine).
  If Sync is false, the timestamps are ignored and the packets are sent as fat as possible.
*/

INT NPF_BufferedWrite(IN PIRP Irp, 
						IN PCHAR UserBuff, 
						IN ULONG UserBuffSize,
						BOOLEAN sync);

/*!
  \brief Ends a send operation.
  \param ProtocolBindingContext Context of the function. Contains a pointer to the OPEN_INSTANCE structure associated with the current instance.
  \param pRequest Pointer to the NDIS PACKET structure used by NPF_Write() to send the packet. 
  \param Status Status of the operation.

  Callback function associated with the NdisSend() NDIS function. It is invoked by NDIS when the NIC 
  driver has finished an OID request operation that was previously started by NPF_Write().
*/
VOID
NPF_SendComplete(
    IN NDIS_HANDLE   ProtocolBindingContext,
    IN PNDIS_PACKET  pPacket,
    IN NDIS_STATUS   Status
    );

/*!
  \brief Ends a reset of the adapter.
  \param ProtocolBindingContext Context of the function. Contains a pointer to the OPEN_INSTANCE structure associated with the current instance.
  \param Status Status of the operation.

  Callback function associated with the NdisReset() NDIS function. It is invoked by NDIS when the NIC 
  driver has finished an OID request operation that was previously started by NPF_IoControl(), in an IOCTL_PROTOCOL_RESET 
  command.
*/
VOID
NPF_ResetComplete(
    IN NDIS_HANDLE  ProtocolBindingContext,
    IN NDIS_STATUS  Status
    );

/*!
  \brief Callback for NDIS StatusHandler. Not used by NPF
*/
VOID
NPF_Status(
    IN NDIS_HANDLE   ProtocolBindingContext,
    IN NDIS_STATUS   Status,
    IN PVOID         StatusBuffer,
    IN UINT          StatusBufferSize
    );


/*!
  \brief Callback for NDIS StatusCompleteHandler. Not used by NPF
*/
VOID
NPF_StatusComplete(IN NDIS_HANDLE  ProtocolBindingContext);

/*!
  \brief Function called by the OS when NPF is unloaded.
  \param DriverObject The driver object of NPF created by the system.

  This is the last function executed when the driver is unloaded from the system. It frees global resources,
  delete the devices and deregisters the protocol. The driver can be unloaded by the user stopping the NPF
  service (from control panel or with a console 'net stop npf').
*/
VOID
NPF_Unload(IN PDRIVER_OBJECT DriverObject);


/*!
  \brief Function that serves the user's reads.
  \param DeviceObject Pointer to the device used by the user.
  \param Irp Pointer to the IRP containing the user request.
  \return The status of the operation. See ntstatus.h in the DDK.

  This function is called by the OS in consequence of user ReadFile() call. It moves the data present in the
  kernel buffer to the user buffer associated with Irp.
  First of all, NPF_Read checks the amount of data in kernel buffer associated with current NPF instance. 
  - If the instance is in capture mode and the buffer contains more than OPEN_INSTANCE::MinToCopy bytes,
  NPF_Read moves the data in the user buffer and returns immediatly. In this way, the read performed by the
  user is not blocking.
  - If the buffer contains less than MinToCopy bytes, the application's request isn't 
  satisfied immediately, but it's blocked until at least MinToCopy bytes arrive from the net 
  or the timeout on this read expires. The timeout is kept in the OPEN_INSTANCE::TimeOut field.
  - If the instance is in statistical mode or in dump mode, the application's request is blocked until the 
  timeout kept in OPEN_INSTANCE::TimeOut expires.
*/
NTSTATUS
NPF_Read(
    IN PDEVICE_OBJECT DeviceObject,
    IN PIRP Irp
    );

/*!
  \brief Reads the registry keys associated woth NPF if the driver is manually installed via the control panel.

  Normally not used in recent versions of NPF.
*/
NTSTATUS
NPF_ReadRegistry(
    IN  PWSTR              *MacDriverName,
    IN  PWSTR              *PacketDriverName,
    IN  PUNICODE_STRING     RegistryPath
    );

/*!
  \brief Function used by NPF_ReadRegistry() to quesry the registry keys associated woth NPF if the driver 
  is manually installed via the control panel.

  Normally not used in recent versions of NPF.
*/
NTSTATUS
NPF_QueryRegistryRoutine(
    IN PWSTR     ValueName,
    IN ULONG     ValueType,
    IN PVOID     ValueData,
    IN ULONG     ValueLength,
    IN PVOID     Context,
    IN PVOID     EntryContext
    );

/*!
  \brief Callback for NDIS BindAdapterHandler. Not used by NPF.
  
  Function called by NDIS when a new adapter is installed on the machine With Plug and Play.
*/
VOID NPF_BindAdapter(
    OUT PNDIS_STATUS            Status,
    IN  NDIS_HANDLE             BindContext,
    IN  PNDIS_STRING            DeviceName,
    IN  PVOID                   SystemSpecific1,
    IN  PVOID                   SystemSpecific2
    );

/*!
  \brief Callback for NDIS UnbindAdapterHandler.
  \param Status out variable filled by NPF_UnbindAdapter with the status of the unbind operation.
  \param ProtocolBindingContext Context of the function. Contains a pointer to the OPEN_INSTANCE structure associated with current instance.
  \param UnbindContext Specifies a handle, supplied by NDIS, that NPF can use to complete the opration.
  
  Function called by NDIS when a new adapter is removed from the machine without shutting it down.
  NPF_UnbindAdapter closes the adapter calling NdisCloseAdapter() and frees the memory and the structures
  associated with it. It also releases the waiting user-level app and closes the dump thread if the instance
  is in dump mode.
*/
VOID
NPF_UnbindAdapter(
    OUT PNDIS_STATUS        Status,
    IN  NDIS_HANDLE         ProtocolBindingContext,
    IN  NDIS_HANDLE         UnbindContext
    );

/*!
  \brief Validates a filtering program arriving from the user-level app.
  \param f The filter.
  \param len Its length, in pseudo instructions.
  \param mem_ex_size The length of the extended memory, used to validate LD/ST to that memory
  \return true if f is a valid filter program..
  
  The kernel needs to be able to verify an application's filter code. Otherwise, a bogus program could easily 
  crash the system.
  This function returns true if f is a valid filter program. The constraints are that each jump be forward and 
  to a valid code.  The code must terminate with either an accept or reject. 
*/
int bpf_validate(struct bpf_insn *f,int len, uint32 mem_ex_size);

/*!
  \brief The filtering pseudo-machine interpreter.
  \param pc The filter.
  \param p Pointer to a memory buffer containing the packet on which the filter will be executed.
  \param wirelen Original length of the packet.
  \param buflen Current length of the packet. In some cases (for example when the transfer of the packet to the RAM
  has not yet finished), bpf_filter can be executed on a portion of the packet.
  \param mem_ex The extended memory.
  \param tme The virtualization of the TME co-processor
  \param time_ref Data structure needed by the TME co-processor to timestamp data
  \return The portion of the packet to keep, in bytes. 0 means that the packet must be rejected, -1 means that
   the whole packet must be kept.
  
  \note this function is not used in normal situations, because the jitter creates a native filtering function
  that is faster than the interpreter.
*/
UINT bpf_filter(register struct bpf_insn *pc,
				register UCHAR *p,
				UINT wirelen,
				register UINT buflen,
				PMEM_TYPE mem_ex,
				PTME_CORE tme,
				struct time_conv *time_ref);

/*!
  \brief The filtering pseudo-machine interpreter with two buffers. This function is slower than bpf_filter(), 
  but works correctly also if the MAC header and the data of the packet are in two different buffers.
  \param pc The filter.
  \param p Pointer to a memory buffer containing the MAC header of the packet.
  \param pd Pointer to a memory buffer containing the data of the packet.
  \param wirelen Original length of the packet.
  \param buflen Current length of the packet. In some cases (for example when the transfer of the packet to the RAM
  has not yet finished), bpf_filter can be executed on a portion of the packet.
  \param mem_ex The extended memory.
  \param tme The virtualization of the TME co-processor
  \param time_ref Data structure needed by the TME co-processor to timestamp data
  \return The portion of the packet to keep, in bytes. 0 means that the packet must be rejected, -1 means that
   the whole packet must be kept.
  
  This function is used when NDIS passes the packet to NPF_tap() in two buffers instaed than in a single one.
*/
UINT bpf_filter_with_2_buffers(register struct bpf_insn *pc,
							   register UCHAR *p,
							   register UCHAR *pd,
							   register int headersize,
							   UINT wirelen,
							   register UINT buflen,
							   PMEM_TYPE mem_ex,
				               PTME_CORE tme,
							   struct time_conv *time_ref);

/*!
  \brief Creates the file that will receive the packets when the driver is in dump mode.
  \param Open The NPF instance that opens the file.
  \param fileName Pointer to a UNICODE string containing the name of the file.
  \param append Boolean value that specifies if the data must be appended to the file.
  \return The status of the operation. See ntstatus.h in the DDK.
*/
NTSTATUS NPF_OpenDumpFile(POPEN_INSTANCE Open , PUNICODE_STRING fileName, BOOLEAN append);

/*!
  \brief Starts dump to file.
  \param Open The NPF instance that opens the file.
  \return The status of the operation. See ntstatus.h in the DDK.

  This function performs two operations. First, it writes the libpcap header at the beginning of the file.
  Second, it starts the thread that asynchronously dumps the network data to the file.
*/
NTSTATUS NPF_StartDump(POPEN_INSTANCE Open);

/*!
  \brief The dump thread.
  \param Open The NPF instance that creates the thread.

  This function moves the content of the NPF kernel buffer to file. It runs in the user context, so at lower 
  priority than the TAP.
*/
VOID NPF_DumpThread(PVOID Open);

/*!
  \brief Saves the content of the packet buffer to the file associated with current instance.
  \param Open The NPF instance that creates the thread.

  Used by NPF_DumpThread() and NPF_CloseDumpFile().
*/
NTSTATUS NPF_SaveCurrentBuffer(POPEN_INSTANCE Open);

/*!
  \brief Writes a block of packets on the dump file.
  \param FileObject The file object that will receive the packets.
  \param Offset The offset in the file where the packets will be put.
  \param Length The amount of bytes to write.
  \param Mdl MDL mapping the memory buffer that will be written to disk.
  \param IoStatusBlock Used by the function to return the status of the operation.
  \return The status of the operation. See ntstatus.h in the DDK.

  NPF_WriteDumpFile addresses directly the file system, creating a custom IRP and using it to send a portion
  of the NPF circular buffer to disk. This function is used by NPF_DumpThread().
*/
VOID NPF_WriteDumpFile(PFILE_OBJECT FileObject,
			                    PLARGE_INTEGER Offset,
								ULONG Length,
								PMDL Mdl,
								PIO_STATUS_BLOCK IoStatusBlock);



/*!
  \brief Closes the dump file associated with an instance of the driver.
  \param Open The NPF instance that closes the file.
  \return The status of the operation. See ntstatus.h in the DDK.
*/
NTSTATUS NPF_CloseDumpFile(POPEN_INSTANCE Open);

/*!
  \brief Returns the amount of bytes present in the packet buffer.
  \param Open The NPF instance that closes the file.
*/
UINT GetBuffOccupation(POPEN_INSTANCE Open);

/*!
  \brief Called by NDIS to notify us of a PNP event. The most significant one for us is power state change.

  \param ProtocolBindingContext Pointer to open context structure. This is NULL for global reconfig 
  events.
  \param pNetPnPEvent Pointer to the PnP event

  If there is a power state change, the driver is forced to resynchronize the global timer.
  This hopefully avoids the synchronization issues caused by hibernation or standby.
  This function is excluded from the NT4 driver, where PnP is not supported
*/
#ifdef NDIS50
NDIS_STATUS NPF_PowerChange(IN NDIS_HANDLE ProtocolBindingContext, IN PNET_PNP_EVENT pNetPnPEvent);
#endif

/**
 *  @}
 */

/**
 *  @}
 */

#endif  /*main ifndef/define*/