Changeset 1296


Ignore:
Timestamp:
11/02/07 15:49:32 (6 years ago)
Author:
perry
Message:

Try and clarify the documentation about the *remaining parameter in the
trace_get_payload_from_* functions

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/lib/libtrace.h.in

    r1286 r1296  
    940940 * @param packet the packet pointer 
    941941 * @param[out] linktype the linktype of the returned pointer 
    942  * @param[out] remaining the capture length (number of valid bytes from the 
    943  * pointer) 
     942 * @param[out] remaining the capture length (the number of captured bytes from 
     943 * the returned pointer) 
    944944 * @return a pointer to the first byte of the packet 
    945945 */ 
    … …  
    964964 * 
    965965 * @return a pointer to the IPv4 header, or NULL if there is no IPv4 header 
     966 * 
     967 * You should consider using \ref trace_get_layer3 instead of this function. 
    966968 */ 
    967969DLLEXPORT SIMPLE_FUNCTION 
    … …  
    972974 * 
    973975 * @return a pointer to the IPv6 header, or NULL if there is no IPv6 header 
     976 * 
     977 * You should consider using \ref trace_get_layer3 instead of this function. 
    974978 */ 
    975979DLLEXPORT SIMPLE_FUNCTION 
    … …  
    991995 * @param packet the libtrace packet 
    992996 * @param[out] linktype the linktype of the returned metadata header 
    993  * @param[out] remaining the amount of space availabled after this header 
    994  * @return a pointer to the first metadata header, or NULL if there are no metadata headers present. 
     997 * @param[out] remaining the number of bytes captured after the returned 
     998 * pointer. 
     999 * @return a pointer to the first metadata header, or NULL if there are no 
     1000 * metadata headers present. 
    9951001 * 
    9961002 * remaining may be NULL, however linktype must be provided. 
    … …  
    10651071 * 
    10661072 * Remaining may be NULL.  If Remaining is not NULL it must point to the number 
    1067  * of bytes captured of the layer2 header and beyond.  It will be updated after 
    1068  * this function to the number of bytes remaining after the layer2 header 
    1069  * was removed. 
     1073 * of bytes captured of the layer2 header and beyond.  It will be decremented 
     1074 * by the number of bytes skipped to find the payload. 
    10701075 * 
    10711076 */ 
    … …  
    10831088 * 
    10841089 * @return a pointer to the layer 3 header. 
    1085  * remaining may be NULL, otherwise it will be filled in by the remaining size 
    1086  * of the captured packet. 
     1090 * remaining may be NULL, otherwise it will be set to the number of captured 
     1091 * bytes after the pointer returned. 
    10871092 */ 
    10881093DLLEXPORT SIMPLE_FUNCTION 
    … …  
    10941099 * @param[out] proto    transport layer protocol 
    10951100 * 
    1096  * @return a pointer to the transport layer header, or NULL if there is no header 
     1101 * @return a pointer to the transport layer header, or NULL if there is no 
     1102 * header 
    10971103 * 
    10981104 * @note proto may be NULL if proto is unneeded. 
    10991105 */ 
    1100 DLLEXPORT void *trace_get_transport(const libtrace_packet_t *packet, uint8_t *proto,  
    1101                 uint32_t *remaining); 
     1106DLLEXPORT void *trace_get_transport(const libtrace_packet_t *packet,  
     1107                uint8_t *proto, uint32_t *remaining); 
    11021108 
    11031109/** Gets a pointer to the payload given a pointer to the IP header 
    … …  
    11061112 * @param[in,out] remaining Updated with the number of bytes remaining 
    11071113 * 
    1108  * @return a pointer to the transport layer header, or NULL if header isn't present. 
     1114 * @return a pointer to the transport layer header, or NULL if header isn't 
     1115 * present. 
    11091116 * 
    11101117 * Remaining may be NULL.  If Remaining is not NULL it must point to the number 
    1111  * of bytes captured of the IP header and beyond.  It will be updated after this 
    1112  * function to the number of bytes remaining after the IP header (and any IP options) 
    1113  * have been removed. 
     1118 * of bytes captured of the IP header and beyond.  It will be decremented by 
     1119 * the length of the IPv4 header (including any options). 
    11141120 * 
    11151121 * proto may be NULL if not needed. 
    … …  
    11251131 * @param[in,out] remaining Updated with the number of bytes remaining 
    11261132 * 
    1127  * @return a pointer to the transport layer header, or NULL if the IPv6 header isn't complete. 
     1133 * @return a pointer to the transport layer header, or NULL if the IPv6 header 
     1134 * isn't complete. 
    11281135 * 
    11291136 * Remaining may be NULL.  If Remaining is not NULL it must point to the number 
    1130  * of bytes captured of the IP header and beyond.  It will be updated after this 
    1131  * function to the number of bytes remaining after the IP header (and any IP options) 
    1132  * have been removed. 
     1137 * of bytes captured of the IP header and beyond.  It will be decremented by 
     1138 * this function by the length of the IPV6 header. 
    11331139 * 
    11341140 * proto may be NULL if not needed. 
    … …  
    11591165 
    11601166/** Skips over any 802.1q headers, if present. 
    1161  * @param ethernet      A pointer to the payload following an ethernet header -usually the result of calling trace_get_payload_from_link 
     1167 * @param ethernet      A pointer to the payload following an ethernet header 
     1168 * -usually the result of calling trace_get_payload_from_link 
    11621169 * @param[in,out] type  The ethernet type, replaced with the vlan ether type 
    11631170 * @param[in,out] remaining Updated with the number of bytes remaining 
    … …  
    11671174 * 
    11681175 * Remaining may be NULL. If Remaining is not NULL it must point to the number 
    1169  * of bytes captured past (but not including) the link layer. It will be 
    1170  * updated after this function to the number of bytes remaining after the 
    1171  * vlan header. If it is unchanged then no vlan header exists. 
     1176 * of bytes captured past (but not including) the link layer. This function 
     1177 * will decrement it by the length of the 802.1q headers if present. 
    11721178 * 
    11731179 * Type must point to the value of the ethernet type. Libtrace will assert 
    … …  
    11851191 * 
    11861192 * Remaining may be NULL.  If remaining is not NULL it must point to the number 
    1187  * of bytes captured of the TCP header and beyond.  It will be updated after 
    1188  * this function to the number of bytes remaining after the TCP header (and any 
    1189  * TCP options) have been removed. 
     1193 * of bytes captured of the TCP header and beyond.  It will be decremented by 
     1194 * this function by the length of the TCP header (including any options). 
    11901195 * 
    11911196 */ 
    … …  
    12001205 * 
    12011206 * Remaining may be NULL.  If Remaining is not NULL it must point to the number 
    1202  * of bytes captured of the UDP header and beyond.  It will be updated after 
     1207 * of bytes captured of the UDP header and beyond.  It will be decremented by 
    12031208 * this function to the number of bytes remaining after the UDP header. 
    12041209 * 
    … …  
    12131218 * 
    12141219 * Remaining may be NULL.  If remaining is not NULL it must point to the number 
    1215  * of bytes captured of the ICMP header and beyond.  It will be updated after 
    1216  * this function to the number of bytes remaining after the ICMP header. 
     1220 * of bytes captured of the ICMP header and beyond.  It will be decremented 
     1221 * by the number of bytes in the ICMP header. 
    12171222 *  
    12181223 */ 
    … …  
    12241229 * 
    12251230 * @return a pointer to the TCP header, or NULL if there is not a TCP packet 
     1231 * 
     1232 * @note you should probably use trace_get_transport() 
    12261233 */ 
    12271234DLLEXPORT SIMPLE_FUNCTION 
    … …  
    12351242 * 
    12361243 * Remaining may be NULL.  If Remaining is not NULL it must point to the number 
    1237  * of bytes captured of the TCP header and beyond.  It will be updated after 
    1238  * this function to the number of bytes remaining after the TCP header (and any 
    1239  * TCP options) have been removed. 
     1244 * of bytes captured of the TCP header and beyond.  It will be decremented by 
     1245 * the number of bytes in the TCP header (including any TCP options). 
    12401246 * 
    12411247 * @note The last parameter has changed from libtrace2 
    … …  
    12591265 * 
    12601266 * Remaining may be NULL.  If Remaining is not NULL it must point to the number 
    1261  * of bytes captured of the UDP header and beyond.  It will be updated after 
    1262  * this function to the number of bytes remaining after the UDP header have 
    1263  * been removed. 
     1267 * of bytes captured of the UDP header and beyond.  This function will 
     1268 * decremented it by the length of the UDP header. 
    12641269 * 
    12651270 * @note Beware the change from libtrace2 from skipped to remaining 
    … …  
    12831288 * 
    12841289 * Remaining may be NULL.  If Remaining is not NULL it must point to the number 
    1285  * of bytes captured of the ICMP header and beyond.  It will be updated after 
    1286  * this function to the number of bytes remaining after the ICMP header. 
     1290 * of bytes captured of the ICMP header and beyond.  It will be decremented by 
     1291 * the length of the ICMP head in bytes. 
    12871292 * 
    12881293 * @note Beware the change from libtrace2 from skipped to remaining 
Note: See TracChangeset for help on using the changeset viewer.