PacketMonitorAddCaptureConstraint function

2024-07-10

Description

This function is used to apply constraints to packets which are reported by packet monitor.

This function is used to specify constraints/filters on packet capture for a Packet Monitor Session. Only those packets which satisfy the constraints added to a session will be captured by Packet Monitor. Multiple constraints can be added to a session in which case a packet will be captured if it matches any one of the added constraints. If no constraints have been added to a session, all packets will be captured.

Syntax

HRESULT
WINAPI
PacketMonitorAddCaptureConstraint(
    _In_ PACKETMONITOR_SESSION session,
    _In_ PACKETMONITOR_PROTOCOL_CONSTRAINT const* captureConstraint
    );

Parameters

[in] session

Packet Monitor Session to which this constraint will be applied as filter for Packet Monitoring. A session object can be created by calling PacketMonitorCreateLiveSession.

[in] captureConstraint

Pointer to variable of type PACKETMONITOR_PROTOCOL_CONSTRAINT specifying the constraint to be applied on the packets for the session. Packet monitor will only report packets for which the header data matches with all the fields set in this struct.

typedef struct PACKETMONITOR_PROTOCOL_CONSTRAINT
{
    WCHAR Name[PACKETMONITOR_MAX_NAME_LENGTH];

    union
    {
        struct
        {
            UINT Mac1 : 1;
            UINT Mac2 : 1;
            UINT VlanId : 1;
            UINT EtherType : 1;

            UINT DSCP : 1;
            UINT TransportProtocol : 1;
            UINT Ip1 : 1;
            UINT Ip2 : 1;
            UINT IPv6 : 1; // indicate IP version

            UINT PrefixLength1 : 1;
            UINT PrefixLength2 : 1;

            UINT Port1 : 1;
            UINT Port2 : 1;
            UINT TCPFlags : 1;
            UINT EncapType : 1;
            UINT VxLanPort : 1;

            UINT ClusterHeartbeat : 1;

        } IsPresent;

        UINT IsPresentValue;
    };

    // Ethernet frame
    UCHAR Mac1[PACKETMONITOR_MAC_ADDRESS_SIZE];
    UCHAR Mac2[PACKETMONITOR_MAC_ADDRESS_SIZE];

    USHORT VlanId;

    USHORT EtherType; 

    // IP header
    USHORT DSCP;
    UCHAR TransportProtocol;

    PACKETMONITOR_IP_ADDRESS Ip1;
    PACKETMONITOR_IP_ADDRESS Ip2;

    UCHAR PrefixLength1;
    UCHAR PrefixLength2;

    // TCP or UDP header
    USHORT Port1;
    USHORT Port2;

    UCHAR TCPFlags;

    // Encapsulation
    ULONG EncapType;
    USHORT VxLanPort;

    // Counters
    UINT64 Packets;
    UINT64 Bytes;
} PACKETMONITOR_PROTOCOL_CONSTRAINT;

typedef union PACKETMONITOR_IP_ADDRESS
{
    ULONG IPv4;
    UCHAR IPv4_bytes[PACKETMONITOR_IPV4_ADDRESS_SIZE];
 
    ULONGLONG IPv6[PACKETMONITOR_IPV6_ADDRESS_SIZE / sizeof(ULONGLONG)];
    UCHAR IPv6_bytes[PACKETMONITOR_IPV6_ADDRESS_SIZE];
} PACKETMONITOR_IP_ADDRESS;

Mac1 – Mac Address of Source if IsPresent.Mac1 is TRUE.
Mac2 – Mac Address of Destination if IsPresent.Mac2 is TRUE.
EtherType – Ethernet Type Value if IsPresent.EtherType is TRUE.
DSCP – Field in the IP header if IsPresent.DSCP is TRUE.
TransportProtocol – Type of Protocol (UDP – 17, TCP – 6, etc.)
Ip1 – Ip Address of Source if IsPresent.Ip1 is TRUE.
Ip2 – Ip Address of Destination if IsPresent.Ip2 is TRUE.
Port1 – Source Port Number if IsPresent.Port1 is TRUE.
Port2 – Destination Port Number if IsPresent.Port1 is TRUE.
TCPFlags – TCP Flags if IsPresent.TCPFlags is TRUE.
VxLanPort – VxLanPort if IsPresent. VxLanPort is TRUE
EncapType – Encapsulation type for packets. Supported Values are:
- 0x00 – No Encapsulation (Default)
- 0x01 – VxLan Encapsulation
- 0x02 – GRE(Generic Routing Encapsulation) encapsulation
- 0x04 – IP inside IP packet Encapsulation
- 0xFF – All Encapsulation supported.
Packets - Not Implemented Bytes - Not Implemented

Returns

If the function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

‘IsPresent’ struct inside ‘PACKETMONITOR_PROTOCOL_CONSTRAINT’ behaves as a flag to specify which corresponding field contains a value.

Remarks

This can be called either before or after activating a Session.

Share via