Changeset 1268

Timestamp:

05/09/07 23:52:26 (1 year ago)

Author:

smr26

Message:

* Deprecate the use of trace_get_link()
* Replace trace_get_link() with trace_get_packet_buffer()
* Introduce new API for dealing with metadata headers such as Radiotap or Linux

SLL

* Introduce trace_get_layer2() which returns the start of the layer 2 header,

which is usually the start of the packet as it was seen on the wire.

Files:

• trunk/lib/libtrace.h.in (modified) (5 diffs)
• trunk/lib/protocols.c (modified) (1 diff)
• trunk/lib/trace.c (modified) (1 diff)

trunk/lib/libtrace.h.in

@@ -142 +142 @@
- */
-#if __GNUC__ >= 3 
+#  define DEPRECATED __attribute__((deprecated))
-#  define SIMPLE_FUNCTION __attribute__((pure))
-#  define UNUSED __attribute__((unused))
@@ -147 +148 @@
-#  define PRINTF(formatpos,argpos) __attribute__((format(printf,formatpos,argpos)))
-#else
+#  define DEPRECATED
-#  define SIMPLE_FUNCTION
-#  define UNUSED
@@ -941 +943 @@
- */
-
+
+/* Gets a pointer to the first byte of the packet as it was captured and
+ * returns its corresponding linktype and capture length.
+ *
+ * Use this function instead of the deprecated trace_get_link().
+ *
+ * @param packet the packet pointer
+ * @param linktype[out] the linktype of the returned pointer
+ * @param remaining[out] the capture length (number of valid bytes from the
+ * pointer)
+ * @return a pointer to the first byte of the packet
+ */
+DLLEXPORT void *trace_get_packet_buffer(const libtrace_packet_t *packet,
+                libtrace_linktype_t *linktype, uint32_t *remaining);
+
-/** get a pointer to the link layer
- * @param packet        the packet opaque pointer
@@ -946 +963 @@
- * @return a pointer to the link layer, or NULL if there is no link layer
- *
+ * @deprecated This function is deprecated. Use trace_get_packet_buffer(..) or
+ * one of the trace_get_layer*(..) functions instead.
- * @note you should call trace_get_link_type to find out what type of link
- * layer this is
- */
-
+ DEPRECATED
-void *trace_get_link(const libtrace_packet_t *packet);
-
@@ -967 +986 @@
-DLLEXPORT SIMPLE_FUNCTION
-libtrace_ip6_t *trace_get_ip6(libtrace_packet_t *packet);
+
+/* Return a pointer to the first metadata header in a packet, if present.
+ *
+ * This function takes a pointer to a libtrace packet and if any metadata
+ * headers exist, returns a pointer to the first one, along with its
+ * corresponding linktype. 
+ *
+ * If no metadata headers exist in the packet, NULL is returned.
+ *
+ * A metadata header is a header that was prepended by the capturing device,
+ * such as a Linux SLL header, or a Radiotap wireless monitoring header.
+ * Subsequent metadata headers may be accessed with the
+ * trace_get_payload_from_meta(...) function. 
+ *
+ * @param packet the libtrace packet
+ * @param linktype[out] the linktype of the returned metadata header
+ * @param remaining[out] the amount of space availabled after this header
+ * @return a pointer to the first metadata header, or NULL if there are no metadata headers present.
+ *
+ * remaining may be NULL, however linktype must be provided.
+ */
+DLLEXPORT void *trace_get_packet_meta(const libtrace_packet_t *packet,
+                libtrace_linktype_t *linktype,
+                uint32_t *remaining);
+
+/* Returns the payload of a metadata header.
+ * 
+ * This function takes a pointer to the start of a metadata header (either
+ * obtained via trace_get_packet_meta(...) or by a previous call to
+ * trace_get_payload_from_meta(...)) along with its corresponding linktype and
+ * returns the payload, i.e. the next header. It will also update the linktype
+ * parameter to indicate the type of payload.
+ *  
+ * If the linktype indicates that the header passed in is not a metadata
+ * header, the function returns NULL to indicate this. The linktype remains
+ * unchanged in this case.
+ *
+ * This function allows the user to iterate through metadata headers which are
+ * sometimes present before the actual packet as it was received on the wire.
+ * Examples of metadata headers include the Linux SLL header and the Radiotap
+ * wireless monitoring header.
+ *
+ * @param meta[in] a pointer to a header
+ * @param linktype[in,out] the linktype of meta (updated to indicate the
+ * linktype of the returned header if applicable).
+ * @param remaining[in,out] the number of bytes after the meta pointer.
+ * @return a pointer to the payload of the metadata header. If meta is not a
+ * pointer to a metadata header, NULL is returned and linktype remains
+ * unchanged.
+ *
+ * All parameters are mandatory. NULL will be returned if any are NULL.
+ */
+DLLEXPORT void *trace_get_payload_from_meta(const void *meta,
+                libtrace_linktype_t *linktype,
+                uint32_t *remaining);
+
+
+/* Get a pointer to the layer 2 header. Generally this is the first byte of the
+ * packet as it was seen on the wire.
+ * 
+ * This function takes a libtrace packet and skips over any metadata headers if
+ * present (such as Linux SLL or Radiotap) and returns a pointer to the first
+ * byte of the packet that was actually received by the network interface.
+ *
+ * @param packet the libtrace packet
+ * @param linktype[out] the linktype of the returned layer 2 header
+ * @param remaining[out] the number of bytes left in the packet after the
+ * returned pointer.
+ * @return a pointer to the first byte of the packet as it was seen on the
+ * wire.
+ *
+ * remaining may be NULL, otherwise it will be filled in by the function.
+ */
+DLLEXPORT void *trace_get_layer2(const libtrace_packet_t *packet,
+                libtrace_linktype_t *linktype,
+                uint32_t *remaining);
-
-/** Get a pointer to the layer 3 header.

trunk/lib/protocols.c

@@ -442 +442 @@
-}
-
+DLLEXPORT void *trace_get_packet_meta(const libtrace_packet_t *packet, 
+                libtrace_linktype_t *linktype,
+                uint32_t *remaining)
+{
+        uint32_t dummyrem = trace_get_capture_length(packet);
+
+        assert(packet != NULL);
+        assert(linktype != NULL);
+        
+        if (remaining == NULL) 
+                remaining = &dummyrem;
+        
+        void *pktbuf = trace_get_packet_buffer(packet, linktype, remaining);
+        switch (*linktype) {
+                case TRACE_TYPE_LINUX_SLL:
+                case TRACE_TYPE_80211_RADIO:
+                case TRACE_TYPE_80211_PRISM:
+                        return pktbuf;
+                case TRACE_TYPE_HDLC_POS:
+                case TRACE_TYPE_ETH:
+                case TRACE_TYPE_ATM:
+                case TRACE_TYPE_80211:
+                case TRACE_TYPE_NONE:
+                case TRACE_TYPE_PFLOG:
+                case TRACE_TYPE_POS:
+                case TRACE_TYPE_AAL5:
+                case TRACE_TYPE_DUCK:
+                case TRACE_TYPE_LLCSNAP:
+                case TRACE_TYPE_PPP:
+                case TRACE_TYPE_METADATA:
+                        return NULL;
+        }
+}
+
+DLLEXPORT void *trace_get_payload_from_meta(const void *meta,
+                libtrace_linktype_t *linktype,
+                uint32_t *remaining)
+{
+        void *nexthdr; 
+        uint16_t arphrd;
+        
+        assert(meta != NULL);
+        assert(linktype != NULL);
+        assert(remaining != NULL);
+        
+        switch(*linktype) {
+                case TRACE_TYPE_LINUX_SLL:
+                        nexthdr = trace_get_payload_from_linux_sll(meta,
+                                        &arphrd, remaining);
+                        *linktype = arphrd_type_to_libtrace(arphrd);
+                        return nexthdr;
+                case TRACE_TYPE_80211_RADIO:
+                        nexthdr = trace_get_payload_from_radiotap(meta,
+                                        linktype, remaining);
+                        return nexthdr;
+                case TRACE_TYPE_80211_PRISM:
+                        nexthdr = trace_get_payload_from_prism(meta,
+                                        linktype, remaining);
+                        return nexthdr;
+                case TRACE_TYPE_HDLC_POS:
+                case TRACE_TYPE_ETH:
+                case TRACE_TYPE_ATM:
+                case TRACE_TYPE_80211:
+                case TRACE_TYPE_NONE:
+                case TRACE_TYPE_PFLOG:
+                case TRACE_TYPE_POS:
+                case TRACE_TYPE_AAL5:
+                case TRACE_TYPE_DUCK:
+                case TRACE_TYPE_LLCSNAP:
+                case TRACE_TYPE_PPP:
+                case TRACE_TYPE_METADATA:
+                        /* In this case, the pointer passed in does not point
+                         * to a metadata header and so we cannot get the
+                         * payload.
+                         */
+                        return NULL;
+        }
+}
+
+DLLEXPORT void *trace_get_layer2(const libtrace_packet_t *packet,
+                libtrace_linktype_t *linktype,
+                uint32_t *remaining) 
+{
+        uint32_t dummyrem;
+        
+        assert(packet != NULL);
+        assert(linktype != NULL);
+
+        if (remaining == NULL)
+                remaining = &dummyrem;
+        
+        void *meta = trace_get_packet_meta(packet, linktype, remaining);
+
+        /* If there are no meta-data headers, we just return the start of the
+         * packet buffer, along with the linktype, etc.
+         */
+        if (meta == NULL) 
+                return trace_get_packet_buffer(packet, linktype, remaining);
+        
+        /* If there are meta-data headers, we need to skip over them until we
+         * find a non-meta data header and return that.
+         */
+        for(;;) {
+                void *nexthdr = trace_get_payload_from_meta(meta, 
+                                linktype, remaining);
+                if (nexthdr == NULL)
+                        return meta;
+                meta = nexthdr;
+        }
+}
+
-DLLEXPORT void *trace_get_layer3(libtrace_packet_t *packet,
-                uint16_t *ethertype,

trunk/lib/trace.c

@@ -760 +760 @@
-}
-
+DLLEXPORT void *trace_get_packet_buffer(const libtrace_packet_t *packet,
+                libtrace_linktype_t *linktype, uint32_t *remaining) {
+        assert(packet != NULL);
+        if (linktype) *linktype = trace_get_link_type(packet);
+        if (remaining) *remaining = trace_get_capture_length(packet);
+        return (void *) packet->payload;
+}
+
-DLLEXPORT void *trace_get_link(const libtrace_packet_t *packet) {
-        return (void *)packet->payload;