This function installs a packet handler for specific packet types on a TCP/IP device driver (e.g. the Ethernet device). After this installation, the user's installed callback function will receive incoming packets from that device which match the packet type specification.
The respective device driver must be calling the pktIncomingPacket() for each incoming packet in order for this packet trap functionality to work. The @CHIP-RTOS-PPC internal Ethernet driver meets this requirements. A list of all installed device drivers with their configuration data is retrieveable by Dev_Get_IfaceEntries(). A specific driver handle can be retrieved by calling Dev_Find_Iface_By_Name().
pktHandle parameter passed to this API references a PktHandle data structure containing a mix of one output and three input parameters. The handle member is an output parameter which will be set to a non-zero value if this API is successful. This handle will be required by the user if the pktReleaseType() API is used.
The other three members of the PktHandle data structure are input parameters provided by the caller to specify the handler's packet trap filter (based on packet type) and a callback function. The packet receiver callback function must satisfy the prototype:
int myPktRecvCb(void * buffer, int length) ;
buffer input parameter will point to the received packet. This packet's size in bytes is specified by the
For efficiency reasons, the packet receiver callback function will be executed in Supervisor mode, instead of the User mode in which application programs normally execute. This means the protection against programming errors offered by the User mode is not in place, and therefore extra care must be taken when programmming these callbacks to avoid bringing down the entire system.
The pktTypePtr and pktTypeSize structure members are used to specify which packets will be passed to your callback by the system. The
wildcard input parameter to this API indicates if you want the packet type data to be used as a mask to qualify the incoming packets, or an exact type match.
wildcard Boolean non-zero for a wild card match. The supplied packet type data will then be bit-wise AND'ed against the incoming packet's type field. If the result of this masking operation is non-zero, then that packet will be delivered to your installed callback function. For example, if a wild card packet type 0xFFFF is installed on the Ethernet device, all received packets are forwarded to the user's handler.
A maximum of 2 wild card handlers are supported per device.
wildcard Boolean to zero to filter out all incoming packets which do not have an exact packet type field match to your specified packet type value. A maximum of 16 specific packet type handlers are supported per device.
If the same packet type and
wildcard flag are supplied as was given for a previous packet handler for this device, then the previous trap will be overwritten with your new data. (This could have the affect of changing the callback vector.)
The system will make a copy of all data supplied by the user to this API, including the data referenced by pktTypePtr. So the PktHandle object need not persist after this API returns.
|[in] ||devHandle ||Device handle pointer, retrievable by Dev_Get_Handle_By_Name().|
|[in,out] ||pktHandle ||The pointer to the storage which contains the required handler data|
PktHandle myPktHandle =
|[in] ||wildcard ||TRUE: Install wild card packet type.|
FALSE: Install specific packet type.
- 0 on success. The
handle member of the pktHandle structure now contains the
handle which will be needed if this packet handler is to be later removed with the pktReleaseType() API.
-1 on failure (bad parameters or all handler slots are already occupied)
- SC2x3 V1.00 - CLIB V1.00
- See also:
- Dev_Find_Iface_By_Name() pktReleaseType()