Finish incorporating timestamp method selection improvements into Npcap/Libpcap

[guyharris]

The call might look like

ULONG * PacketGetTimestampModes(LPADAPTER AdapterObject, UINT *NumModes);

which would return a pointer to an allocated array of ULONG values corresponding to supported time stamp modes and set *NumModes to the number of modes in the array. That might require another routine to free that array.

Alternatively, it might look like

int PacketGetTimestampModes(LPADAPTER AdapterObject, ULONG *Modes)

which:

• if Modes is null, returns either the number of modes on success or -1 on failure;
• if Modes is non-null, fills in *Modes and returns the number of modes on success or -1 on failure.

The caller would first call it with a null Modes, to find out how big a buffer it needs, and then allocate the buffer and call it again with that buffer. I don't expect that the number of available modes will change over time without, for example, installing a newer version of Npcap, so two calls should suffice.

This might be implemented atop BIOCGNUMTIMESTAMPMODES and BIOCGTIMESTAMPMODES ioctls. The first takes an int-sized buffer and fills it in with a count of the number of time stamp modes; the second takes a pointer to the array of ULONG and fills it in.

This would allow libpcap to implement pcap_list_tstamp_types() with Npcap.

[gbloice]

FWIW, the normal Win32 API idiom for such a function would be something like:

STATUS PacketGetTimestampModes(LPADAPTER AdapterObject, ULONG *Modes, ULONG *cNodes)

which returns an API specific STATUS value, normally typed to an integer, e.g. a LONG with 0 as success, anything else is an error and cNodes indicating the elements available in the Modes array on input and the number of elements written to the array on output. Calling with Modes as a nullptr will set the required size in cNodes.

[guyharris]

FWIW, the normal Win32 API idiom for such a function would be something like:

STATUS PacketGetTimestampModes(LPADAPTER AdapterObject, ULONG *Modes, ULONG *cNodes)

which returns an API specific STATUS value, normally typed to an integer, e.g. a LONG with 0 as success, anything else is an error and cNodes indicating the elements available in the Modes array on input and the number of elements written to the array on output. Calling with Modes as a nullptr will set the required size in cNodes.

I know of at least one company up in the US state of Washington that has some APIs that don't follow that convention - those APIs return a BOOL to indicate success or failure, with a status being returned by GetLastError() That's how FlushFileBuffers() works, for example. :-)

Other APIs from that company, such as CreateFile() return HANDLEs, with INVALID_HANDLE indicating failure.

The Packet32.dll routines also follow that convention - not that any of them are APIs; I'm one of the few people who should be writing code that calls them. :-) (I.e., the Packet32.dll API is not guaranteed to be stable; it exists primarily to serve libpcap's pcap-npf.c, and if the API changes, so does pcap-npf.c.)

[gbloice]

FWIW, the normal Win32 API idiom for such a function would be something like:

STATUS PacketGetTimestampModes(LPADAPTER AdapterObject, ULONG *Modes, ULONG *cNodes)

which returns an API specific STATUS value, normally typed to an integer, e.g. a LONG with 0 as success, anything else is an error and cNodes indicating the elements available in the Modes array on input and the number of elements written to the array on output. Calling with Modes as a nullptr will set the required size in cNodes.

I know of at least one company up in the US state of Washington that has some APIs that don't follow that convention - those APIs return a BOOL to indicate success or failure, with a status being returned by GetLastError() That's how FlushFileBuffers() works, for example. :-)

Those ones are annoying, hence I chose the "better" example.

Other APIs from that company, such as CreateFile() return HANDLEs, with INVALID_HANDLE indicating failure.

The Packet32.dll routines also follow that convention - not that any of them are APIs; I'm one of the few people who should be writing code that calls them. :-) (I.e., the Packet32.dll API is not guaranteed to be stable; it exists primarily to serve libpcap's pcap-npf.c, and if the API changes, so does pcap-npf.c.)

My observation, which didn't spell it out, was to move the number of nodes from the return to an in\out parameter, which then allows the return to indicate success or failure, or something richer without having to use "out-of-range" values as the return to indicate things went wrong.

[fyodor]

This is just an update/summary that we added the Packet* calls a while back, but we still need to make and submit a patch to upstream libpcap (and possibly our wpcap.dll while we wait for upstream incorporation). We also should document the Npcap-specific details on how these calls are implemented on Windows into the Npcap users' guide.

[guyharris]

This is just an update/summary that we added the Packet* calls a while back, but we still need to make and submit a patch to upstream libpcap

You added PacketSetTimestampMode(), but not PacketGetTimestampModes(); the libpcap changes will require both.