Changeset 180f095 for lib/libtrace.h.in


Ignore:
Timestamp:
09/05/07 23:52:26 (14 years ago)
Author:
Scott Raynel <smr26@…>
Branches:
4.0.1-hotfixes, cachetimestamps, develop, dpdk-ndag, etsilive, getfragoff, help, libtrace4, master, ndag_format, pfring, rc-4.0.1, rc-4.0.2, rc-4.0.3, rc-4.0.4, ringdecrementfix, ringperformance, ringtimestampfixes
Children:
9bc4689
Parents:
e8a6c52
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.
File:
1 edited

Legend:

Unmodified
Added
Removed
  • lib/libtrace.h.in

    r6399a90 r180f095  
    142142 */
    143143#if __GNUC__ >= 3
     144#  define DEPRECATED __attribute__((deprecated))
    144145#  define SIMPLE_FUNCTION __attribute__((pure))
    145146#  define UNUSED __attribute__((unused))
     
    147148#  define PRINTF(formatpos,argpos) __attribute__((format(printf,formatpos,argpos)))
    148149#else
     150#  define DEPRECATED
    149151#  define SIMPLE_FUNCTION
    150152#  define UNUSED
     
    941943 */
    942944
     945
     946/* Gets a pointer to the first byte of the packet as it was captured and
     947 * returns its corresponding linktype and capture length.
     948 *
     949 * Use this function instead of the deprecated trace_get_link().
     950 *
     951 * @param packet the packet pointer
     952 * @param linktype[out] the linktype of the returned pointer
     953 * @param remaining[out] the capture length (number of valid bytes from the
     954 * pointer)
     955 * @return a pointer to the first byte of the packet
     956 */
     957DLLEXPORT void *trace_get_packet_buffer(const libtrace_packet_t *packet,
     958                libtrace_linktype_t *linktype, uint32_t *remaining);
     959
    943960/** get a pointer to the link layer
    944961 * @param packet        the packet opaque pointer
     
    946963 * @return a pointer to the link layer, or NULL if there is no link layer
    947964 *
     965 * @deprecated This function is deprecated. Use trace_get_packet_buffer(..) or
     966 * one of the trace_get_layer*(..) functions instead.
    948967 * @note you should call trace_get_link_type to find out what type of link
    949968 * layer this is
    950969 */
    951 DLLEXPORT SIMPLE_FUNCTION
     970DLLEXPORT SIMPLE_FUNCTION DEPRECATED
    952971void *trace_get_link(const libtrace_packet_t *packet);
    953972
     
    967986DLLEXPORT SIMPLE_FUNCTION
    968987libtrace_ip6_t *trace_get_ip6(libtrace_packet_t *packet);
     988
     989/* Return a pointer to the first metadata header in a packet, if present.
     990 *
     991 * This function takes a pointer to a libtrace packet and if any metadata
     992 * headers exist, returns a pointer to the first one, along with its
     993 * corresponding linktype.
     994 *
     995 * If no metadata headers exist in the packet, NULL is returned.
     996 *
     997 * A metadata header is a header that was prepended by the capturing device,
     998 * such as a Linux SLL header, or a Radiotap wireless monitoring header.
     999 * Subsequent metadata headers may be accessed with the
     1000 * trace_get_payload_from_meta(...) function.
     1001 *
     1002 * @param packet the libtrace packet
     1003 * @param linktype[out] the linktype of the returned metadata header
     1004 * @param remaining[out] the amount of space availabled after this header
     1005 * @return a pointer to the first metadata header, or NULL if there are no metadata headers present.
     1006 *
     1007 * remaining may be NULL, however linktype must be provided.
     1008 */
     1009DLLEXPORT void *trace_get_packet_meta(const libtrace_packet_t *packet,
     1010                libtrace_linktype_t *linktype,
     1011                uint32_t *remaining);
     1012
     1013/* Returns the payload of a metadata header.
     1014 *
     1015 * This function takes a pointer to the start of a metadata header (either
     1016 * obtained via trace_get_packet_meta(...) or by a previous call to
     1017 * trace_get_payload_from_meta(...)) along with its corresponding linktype and
     1018 * returns the payload, i.e. the next header. It will also update the linktype
     1019 * parameter to indicate the type of payload.
     1020 * 
     1021 * If the linktype indicates that the header passed in is not a metadata
     1022 * header, the function returns NULL to indicate this. The linktype remains
     1023 * unchanged in this case.
     1024 *
     1025 * This function allows the user to iterate through metadata headers which are
     1026 * sometimes present before the actual packet as it was received on the wire.
     1027 * Examples of metadata headers include the Linux SLL header and the Radiotap
     1028 * wireless monitoring header.
     1029 *
     1030 * @param meta[in] a pointer to a header
     1031 * @param linktype[in,out] the linktype of meta (updated to indicate the
     1032 * linktype of the returned header if applicable).
     1033 * @param remaining[in,out] the number of bytes after the meta pointer.
     1034 * @return a pointer to the payload of the metadata header. If meta is not a
     1035 * pointer to a metadata header, NULL is returned and linktype remains
     1036 * unchanged.
     1037 *
     1038 * All parameters are mandatory. NULL will be returned if any are NULL.
     1039 */
     1040DLLEXPORT void *trace_get_payload_from_meta(const void *meta,
     1041                libtrace_linktype_t *linktype,
     1042                uint32_t *remaining);
     1043
     1044
     1045/* Get a pointer to the layer 2 header. Generally this is the first byte of the
     1046 * packet as it was seen on the wire.
     1047 *
     1048 * This function takes a libtrace packet and skips over any metadata headers if
     1049 * present (such as Linux SLL or Radiotap) and returns a pointer to the first
     1050 * byte of the packet that was actually received by the network interface.
     1051 *
     1052 * @param packet the libtrace packet
     1053 * @param linktype[out] the linktype of the returned layer 2 header
     1054 * @param remaining[out] the number of bytes left in the packet after the
     1055 * returned pointer.
     1056 * @return a pointer to the first byte of the packet as it was seen on the
     1057 * wire.
     1058 *
     1059 * remaining may be NULL, otherwise it will be filled in by the function.
     1060 */
     1061DLLEXPORT void *trace_get_layer2(const libtrace_packet_t *packet,
     1062                libtrace_linktype_t *linktype,
     1063                uint32_t *remaining);
    9691064
    9701065/** Get a pointer to the layer 3 header.
Note: See TracChangeset for help on using the changeset viewer.