1 /* 2 ** Copyright (C) 2006-2020 by Carnegie Mellon University. 3 ** 4 ** @OPENSOURCE_LICENSE_START@ 5 ** See license information in ../../LICENSE.txt 6 ** @OPENSOURCE_LICENSE_END@ 7 */ 8 9 /* 10 ** skheader.h 11 ** 12 ** API to read, write, and manipulate the header of a SiLK file 13 ** 14 ** Mark Thomas 15 ** November 2006 16 ** 17 */ 18 #ifndef _SKHEADER_H 19 #define _SKHEADER_H 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 #include <silk/silk.h> 25 26 RCSIDENTVAR(rcsID_SKHEADER_H, "$SiLK: skheader.h ef14e54179be 2020-04-14 21:57:45Z mthomas $"); 27 28 #include <silk/silk_types.h> 29 30 /** 31 * @file 32 * 33 * The API to read, write, and manipulate the header of a binary 34 * SiLK file. 35 * 36 * This file is part of libsilk. 37 */ 38 39 40 /** 41 * A SiLK file has a header-section and a data-section. The header 42 * section is called an 'sk_file_header_t'. 43 * 44 * The sk_file_header_t is split into two sections, a fixed size 45 * 'sk_header_start_t' and a variable number of variable-sized 46 * 'sk_header_entry_t'. 47 */ 48 typedef struct sk_file_header_st sk_file_header_t; 49 50 /** 51 * The first section of an sk_file_header_t is called the 52 * sk_header_start_t, and it has a fixed size of 16 bytes. 53 * 54 * The first four bytes of an sk_header_start_t is the SiLK magic 55 * number, 0xDEADBEEF. 56 * 57 * The next four bytes of the sk_header_start_t denote the file's 58 * byte order, the file's format (that is, the type of data it 59 * contains, the file version, and the type of compression unsed 60 * for the data section. 61 * 62 * The final eight bytes contain the version of SiLK that wrote 63 * the file, the bytes per record, and the version of the record. 64 */ 65 typedef struct sk_header_start_st sk_header_start_t; 66 67 /** 68 * The second part of the sk_file_header_t contains a variable 69 * number of sk_header_entry_t's. 70 */ 71 typedef struct sk_header_entry_st sk_header_entry_t; 72 73 /** 74 * In core, the sk_header_entry_t's are stored in a circular 75 * doubly-linked-linked list of sk_hentry_node_t's. 76 */ 77 typedef struct sk_hentry_node_st sk_hentry_node_t; 78 79 /** 80 * An sk_hentry_iterator_t is used to visit each of the 81 * header-entries in the header. 82 */ 83 typedef struct sk_hentry_iterator_st sk_hentry_iterator_t; 84 85 /** 86 * Each sk_header_entry_t is made up of an sk_header_entry_spec_t 87 * and a variable size data section---which may contain 0 bytes. 88 */ 89 typedef struct sk_header_entry_spec_st sk_header_entry_spec_t; 90 91 /** 92 * The current sk_header_entry_spec_t has four-bytes that specify 93 * its hentry-type-ID, and four-bytes giving the 94 * sk_header_entry_t's complete length---including the length of 95 * the sk_header_entry_spec_t. 96 */ 97 typedef uint32_t sk_hentry_type_id_t; 98 99 /** 100 * The hentry-type-ID "\0\0\0\0" is used to mark the end of the 101 * header entries. The length of this header-entry should still be 102 * valid. In particular, any header padding must be accounted for 103 * in this entry. 104 * 105 * The minimum sized header is 24 bytes. The data section, if 106 * present, begins immediately after the header-entry whose ID is 107 * "\0\0\0\0". 108 * 109 * Note that in the new headers, all values are in network (big) 110 * byte order, so use ntohs() and ntohl() to read them. 111 * 112 * To avoid clashes with existing files, the file_version value for 113 * all files with this new header will be >= 16. 114 */ 115 116 /** 117 * The minimum file version that may be specified to 118 * skHeaderSetFileVersion(). A SiLK tool may accept a lower 119 * version number when reading data, but the version number may not 120 * be lower than this when creating a file. 121 */ 122 #define SK_FILE_VERSION_MINIMUM 16 123 124 /** 125 * The maximum file version that may be specified to 126 * skHeaderSetFileVersion(). 127 */ 128 #define SK_FILE_VERSION_MAXIMUM SK_FILE_VERSION_MINIMUM 129 130 /** 131 * The file version to use as the default. 132 */ 133 #define SK_FILE_VERSION_DEFAULT SK_FILE_VERSION_MINIMUM 134 135 /** 136 * Values returned by the skHeader*() functions. 137 */ 138 typedef enum skHeaderErrorCodes_en { 139 /** Command succeeded. */ 140 SKHEADER_OK = 0, 141 142 /** Memory allocation failed */ 143 SKHEADER_ERR_ALLOC, 144 145 /** Programmer or allocation error: NULL passed as argument to 146 * function */ 147 SKHEADER_ERR_NULL_ARGUMENT, 148 149 /** The file format is not supported */ 150 SKHEADER_ERR_BAD_FORMAT, 151 152 /** The file version is not supported */ 153 SKHEADER_ERR_BAD_VERSION, 154 155 /** Attempt to replace an entry that does not exist */ 156 SKHEADER_ERR_ENTRY_NOTFOUND, 157 158 /** Error in packing an entry */ 159 SKHEADER_ERR_ENTRY_PACK, 160 161 /** Error in reading an entry from disk */ 162 SKHEADER_ERR_ENTRY_READ, 163 164 /** Error in unpacking an entry */ 165 SKHEADER_ERR_ENTRY_UNPACK, 166 167 /** The entry ID is invalid */ 168 SKHEADER_ERR_INVALID_ID, 169 170 /** Attempt to modify a locked header */ 171 SKHEADER_ERR_IS_LOCKED, 172 173 /** Error handling a legacy header */ 174 SKHEADER_ERR_LEGACY, 175 176 /** Header compression value is invalid */ 177 SKHEADER_ERR_BAD_COMPRESSION, 178 179 /** Read fewer bytes than that required to read the header */ 180 SKHEADER_ERR_SHORTREAD, 181 182 /** Header length is longer than expected */ 183 SKHEADER_ERR_TOOLONG 184 } skHeaderErrorCodes_t; 185 186 187 /** 188 * Settings for the header locks 189 */ 190 typedef enum sk_header_lock_en { 191 /** Header is completely modifable */ 192 SKHDR_LOCK_MODIFIABLE, 193 /** Header is completely locked: nothing can be changed nor new 194 * entries added */ 195 SKHDR_LOCK_FIXED, 196 /** Header cannot be changed, but new header entries may be 197 * added. */ 198 SKHDR_LOCK_ENTRY_OK 199 } sk_header_lock_t; 200 201 202 /** 203 * sk_header_entry_spec_t: The header-entries have a 204 * header-entry-spec and a data section. 205 */ 206 struct sk_header_entry_spec_st { 207 /** The ID for this header-entry. 0 marks the final entry */ 208 sk_hentry_type_id_t hes_id; 209 /** Total length of this header entry, including the 210 * header-entry-spec */ 211 uint32_t hes_len; 212 }; 213 214 /** 215 * sk_header_entry_t 216 */ 217 struct sk_header_entry_st { 218 sk_header_entry_spec_t he_spec; 219 void *he_data; 220 }; 221 222 /** 223 * sk_hentry_iterator_t: The hentry-iterator is used to visit the 224 * header-entries. 225 */ 226 struct sk_hentry_iterator_st { 227 const sk_file_header_t *hdr; 228 sk_hentry_node_t *node; 229 sk_hentry_type_id_t htype_filter; 230 }; 231 232 233 /** 234 * The 'sk_hentry_pack_fn_t' is used to write an in-core 235 * header-entry to a binary data file. 236 * 237 * It take pointers to a header entry data structure, 'hentry_in' 238 * and to a byte-array, 'packed_entry_out' of 'packed_avail_size' 239 * bytes, and it fills 'packed_entry_out' with the data in the 240 * 'hentry_in' suitable for writing to a binary stream. The 241 * function returns the number of bytes in 'packed_entry_out' that 242 * were used, i.e., the number of bytes to be written. If 243 * 'packed_entry_out' is too small, the function should return the 244 * number of bytes that would be required to hold all of 245 * 'hentry_in'. The caller will likely grow 'packed_entry_out' and 246 * invoke this function again. 247 * 248 * This function should make certain that the values in the 249 * sk_header_entry_spec_t section of 'packed_entry_out' are in 250 * network (big-endian) byte order. The other values may have any 251 * meaning, as long as the 'sk_hentry_unpack_fn_t' knows how to 252 * decode them. 253 */ 254 typedef ssize_t 255 (*sk_hentry_pack_fn_t)( 256 const sk_header_entry_t *hentry_in, 257 uint8_t *packed_entry_out, 258 size_t packed_avail_size); 259 260 /** 261 * When a binary SiLK file is read, the 'sk_hentry_unpack_fn_t' is 262 * called to convert the bytes to an in-core data structure. 263 * 264 * It takes a pointer to a sk_header_entry_t, 'packed_in'---as read 265 * from a binary stream and packed by the 266 * 'sk_hentry_pack_fn_t'---and allocates and returns a pointer to 267 * the expanded version of the data. 268 */ 269 typedef sk_header_entry_t * 270 (*sk_hentry_unpack_fn_t)( 271 uint8_t *packed_in); 272 273 /** 274 * The 'sk_hentry_copy_fn_t' is used to do a complete (deep) copy 275 * of a header-entry. 276 * 277 */ 278 typedef sk_header_entry_t * 279 (*sk_hentry_copy_fn_t)( 280 const sk_header_entry_t *hentry_in); 281 282 /** 283 * To produce a human-readable form of the header, 284 * 'sk_hentry_print_fn_t' is used. 285 * 286 * It prints the header, 'hentry', to the specified stream, 'fh', 287 * as text. 288 */ 289 typedef void 290 (*sk_hentry_print_fn_t)( 291 const sk_header_entry_t *hentry, 292 FILE *fh); 293 294 /** 295 * A generic callback function for the header entry 'hentry'. One 296 * such use is as function to free() the memory allocated by the 297 * 'sk_hentry_unpack_fn_t'. 298 */ 299 typedef void 300 (*sk_hentry_callback_fn_t)( 301 sk_header_entry_t *hentry); 302 303 /** 304 * When defined and set to a non-empty string, use 0 as the SiLK 305 * version number in the header of files we create. 306 */ 307 #define SILK_HEADER_NOVERSION_ENV "SILK_HEADER_NOVERSION" 308 309 310 /* 311 * ********************************************************************** 312 * 313 * Functions for handling the header and header entries. 314 * 315 * ********************************************************************** 316 */ 317 318 319 /** 320 * Add the Header Entry 'hentry' to the File Header 'hdr'. Return 321 * 0 on sucess, or -1 for the following error conditions: if the 322 * 'hentry' is NULL or if it has a reserved ID, or on memory 323 * allocation error. 324 */ 325 int 326 skHeaderAddEntry( 327 sk_file_header_t *hdr, 328 sk_header_entry_t *hentry); 329 330 331 /** 332 * Possible value for 'copy_flags' parameter of skHeaderCopy() 333 * indicating that the entire header should be copied. 334 */ 335 #define SKHDR_CP_ALL 0xFFFFFFFFu 336 337 /** 338 * Possible value for 'copy_flags' parameter of skHeaderCopy() 339 * indicating that the byte order value should be copied. 340 */ 341 #define SKHDR_CP_ENDIAN (1u << 7) 342 343 /** 344 * Possible value for 'copy_flags' parameter of skHeaderCopy() 345 * indicating that the file format value should be copied. 346 */ 347 #define SKHDR_CP_FORMAT (1u << 8) 348 349 /** 350 * Possible value for 'copy_flags' parameter of skHeaderCopy() 351 * indicating that the file version value should be copied. 352 */ 353 #define SKHDR_CP_FILE_VERS (1u << 9) 354 355 /** 356 * Possible value for 'copy_flags' parameter of skHeaderCopy() 357 * indicating that the compression method value should be copied. 358 */ 359 #define SKHDR_CP_COMPMETHOD (1u << 10) 360 361 /** 362 * Possible value for 'copy_flags' parameter of skHeaderCopy() 363 * indicating that the record length value should be copied. 364 */ 365 #define SKHDR_CP_REC_LEN (1u << 11) 366 367 /** 368 * Possible value for 'copy_flags' parameter of skHeaderCopy() 369 * indicating that the record version value should be copied. 370 */ 371 #define SKHDR_CP_REC_VERS (1u << 12) 372 373 /** 374 * Possible value for 'copy_flags' parameter of skHeaderCopy() 375 * indicating that all header entries should be copied. 376 */ 377 #define SKHDR_CP_ENTRIES (1u << 31) 378 379 /** 380 * Possible value for 'copy_flags' parameter of skHeaderCopy() 381 * indicating that the file parameter values should be copied. 382 */ 383 #define SKHDR_CP_FILE_FLAGS 0x000000FFu 384 385 /** 386 * Possible value for 'copy_flags' parameter of skHeaderCopy() 387 * indicating that the entire header except the header entries 388 * should be copied. 389 */ 390 #define SKHDR_CP_START 0x00FFFFFFu 391 392 /** 393 * Copy the header 'src_hdr' to 'dst_hdr'. The parts of the header 394 * to copy are specified by the 'copy_flags' value. 395 */ 396 int 397 skHeaderCopy( 398 sk_file_header_t *dst_hdr, 399 const sk_file_header_t *src_hdr, 400 uint32_t copy_flags); 401 402 403 /** 404 * Copy all the header entries whose ID is 'entry_id' from 405 * 'src_hdr' to 'dst_hdr'. 406 */ 407 int 408 skHeaderCopyEntries( 409 sk_file_header_t *dst_hdr, 410 const sk_file_header_t *src_hdr, 411 sk_hentry_type_id_t entry_id); 412 413 414 /** 415 * Create and return a new entry that is a (deep) copy of the 416 * header entry 'src_hentry'. Return NULL on failure or if the 417 * 'src_header' refers to the root node. 418 */ 419 sk_header_entry_t * 420 skHeaderEntryCopy( 421 const sk_header_entry_t *src_hentry); 422 423 424 /** 425 * Return the type ID for a header entry. 426 */ 427 #if 0 428 sk_hentry_type_id_t 429 skHeaderEntryGetTypeId( 430 const sk_header_entry_t *hentry); 431 #else 432 # define skHeaderEntryGetTypeId(hentry) ((hentry)->he_spec.hes_id) 433 #endif 434 435 436 /** 437 * Print a textual representation of the Header Entry 'hentry' to 438 * the stream 'fp'. 439 */ 440 void 441 skHeaderEntryPrint( 442 const sk_header_entry_t *hentry, 443 FILE *fp); 444 445 446 /** 447 * Pack the header entry spec 'he_spec' into the octet array 448 * 'out_packed' whose size is 'bufsize'. If 'bufsize' is smaller 449 * than required, write nothing to the buffer. Return the number 450 * of bytes written to the buffer or that would be written to the 451 * buffer if the buffer were large enough. 452 */ 453 size_t 454 skHeaderEntrySpecPack( 455 const sk_header_entry_spec_t *he_spec, 456 uint8_t *out_packed, 457 size_t bufsize); 458 459 460 /** 461 * Unpack the header entry spec from the octet array 'in_packed' 462 * into the 'he_spec' structure. The function assumes the length 463 * of 'in_packed' is at least sizeof(sk_header_entry_spec_t). 464 */ 465 void 466 skHeaderEntrySpecUnpack( 467 sk_header_entry_spec_t *he_spec, 468 const uint8_t *in_packed); 469 470 471 /** 472 * Get the byte order of the records in the file for which 'hdr' is 473 * the header. 474 */ 475 silk_endian_t 476 skHeaderGetByteOrder( 477 const sk_file_header_t *hdr); 478 479 480 /** 481 * Return the compression method used on 'stream'. 482 */ 483 sk_compmethod_t 484 skHeaderGetCompressionMethod( 485 const sk_file_header_t *hdr); 486 487 488 /** 489 * Given the File Header 'hdr', return a pointer to the first 490 * Header Entry that has the given ID, 'entry_id'. 491 */ 492 sk_header_entry_t * 493 skHeaderGetFirstMatch( 494 const sk_file_header_t *hdr, 495 sk_hentry_type_id_t entry_id); 496 497 498 /** 499 * Return the SiLK file output format for the header. Return 500 * SK_INVALID_FILE_FORMAT when header is NULL. 501 */ 502 sk_file_format_t 503 skHeaderGetFileFormat( 504 const sk_file_header_t *header); 505 506 507 /** 508 * Return the version of the file. As of SK_EXPAND_HDR_INIT_VERS, 509 * this is different than the record version. 510 */ 511 sk_file_version_t 512 skHeaderGetFileVersion( 513 const sk_file_header_t *hdr); 514 515 516 /** 517 * Return the complete length of the header, in bytes. 518 */ 519 size_t 520 skHeaderGetLength( 521 const sk_file_header_t *header); 522 523 524 /** 525 * Return the length of the records as defined in the header. 526 */ 527 size_t 528 skHeaderGetRecordLength( 529 const sk_file_header_t *header); 530 531 532 /** 533 * Return the version number of the SiLK file associated with the 534 * header. 535 */ 536 sk_file_version_t 537 skHeaderGetRecordVersion( 538 const sk_file_header_t *header); 539 540 541 /** 542 * Return a value representing the version of silk that wrote this file. 543 */ 544 uint32_t 545 skHeaderGetSilkVersion( 546 const sk_file_header_t *hdr); 547 548 549 /** 550 * Return 1 if the stream associated with 'header' is in native 551 * byte order, or 0 if it is not. 552 */ 553 int 554 skHeaderIsNativeByteOrder( 555 const sk_file_header_t *header); 556 557 558 /** 559 * Bind the Header Entry Iterator 'iter' to the Header Entries in 560 * the File Header 'hdr'. 561 */ 562 void 563 skHeaderIteratorBind( 564 sk_hentry_iterator_t *iter, 565 const sk_file_header_t *hdr); 566 567 568 /** 569 * Bind the Header Entry Iterator 'iter' to the Header Entries 570 * whose type is 'htype' in the File Header 'hdr'. 571 */ 572 void 573 skHeaderIteratorBindType( 574 sk_hentry_iterator_t *iter, 575 const sk_file_header_t *hdr, 576 sk_hentry_type_id_t htype); 577 578 579 /** 580 * For a Header Entry Iterator 'iter' that has been bound to a file 581 * header, return a pointer to the next Header Entry. Returns NULL 582 * if all Header Entries have been processed. 583 */ 584 sk_header_entry_t * 585 skHeaderIteratorNext( 586 sk_hentry_iterator_t *iter); 587 588 589 /** 590 * On the File Header 'hdr', remove every Header Entry whose Header 591 * Entry Type is 'entry_id'. 592 * 593 * Each Header Entry of the specified Type will be passed to the 594 * free function for that Type. 595 * 596 * Return SKHEADER_OK on success. Return SKHEADER_ERR_INVALID_ID 597 * if 'entry_id' is a restricted ID. Return SKHEADER_ERR_IS_LOCKED 598 * if the 'hdr' is locked. 599 */ 600 int 601 skHeaderRemoveAllMatching( 602 sk_file_header_t *hdr, 603 sk_hentry_type_id_t entry_id); 604 605 606 /** 607 * Set the byte order of the records in the file for which 'hdr' is 608 * the header to 'byte_order'. 609 */ 610 int 611 skHeaderSetByteOrder( 612 sk_file_header_t *hdr, 613 silk_endian_t byte_order); 614 615 616 /** 617 * Set the compression method of the records in the file for which 618 * 'hdr' is the header to 'comp_method'. 619 */ 620 int 621 skHeaderSetCompressionMethod( 622 sk_file_header_t *hdr, 623 uint8_t comp_method); 624 625 626 /** 627 * Set the format of the file this header references to 628 * 'file_format'. 629 */ 630 int 631 skHeaderSetFileFormat( 632 sk_file_header_t *hdr, 633 sk_file_format_t file_format); 634 635 636 /** 637 * Set the file version. The value must be between 638 * SK_FILE_VERSION_MINIMUM and SK_FILE_VERSION_MAXIMUM inclusive. 639 * When this function is not called, the file version is that 640 * specified by SK_FILE_VERSION_DEFAULT. 641 * 642 * Return SKHEADER_OK on success. Return 643 * SKHEADER_ERR_NULL_ARGUMENT if 'hdr' is NULL. Return 644 * SKHEADER_ERR_IS_LOCKED if the header is locked. Return 645 * SKHEADER_ERR_BAD_VERSION if 'file_version' is not legal. 646 */ 647 int 648 skHeaderSetFileVersion( 649 sk_file_header_t *hdr, 650 sk_file_version_t file_version); 651 652 653 /** 654 * Set the length of the records in the file for which 'hdr' is the 655 * header to 'rec_len' octets. 656 */ 657 int 658 skHeaderSetRecordLength( 659 sk_file_header_t *hdr, 660 size_t rec_len); 661 662 663 /** 664 * Set the version of the records in the file for which 'hdr' is 665 * the header to 'version'. 666 */ 667 int 668 skHeaderSetRecordVersion( 669 sk_file_header_t *hdr, 670 sk_file_version_t record_version); 671 672 /** 673 * Return a string explaining the error code 'err_code'. 674 */ 675 const char * 676 skHeaderStrerror( 677 ssize_t err_code); 678 679 680 /* 681 * ********************************************************************** 682 * 683 * Functions for handling the header entry types. 684 * 685 * ********************************************************************** 686 */ 687 688 689 /** 690 * Register a Header Type. 691 */ 692 int 693 skHentryTypeRegister( 694 sk_hentry_type_id_t entry_id, 695 sk_hentry_pack_fn_t pack_fn, 696 sk_hentry_unpack_fn_t unpack_fn, 697 sk_hentry_copy_fn_t copy_fn, 698 sk_hentry_callback_fn_t free_fn, 699 sk_hentry_print_fn_t print_fn); 700 701 702 /* 703 * ********************************************************************** 704 * 705 * The 'packedfile' header entry type is used on data files 706 * generated by rwflowpack. It specifies the start-time, 707 * flow-type, and sensor for a packed data * file, e.g. FT_RWSPLIT, 708 * FT_RWWWW. 709 * 710 * ********************************************************************** 711 */ 712 713 #define SK_HENTRY_PACKEDFILE_ID 1 714 715 int 716 skHeaderAddPackedfile( 717 sk_file_header_t *hdr, 718 sktime_t start_time, 719 sk_flowtype_id_t flowtype_id, 720 sk_sensor_id_t sensor_id); 721 722 /** 723 * Return the hour at which data in this file begins. Return 0 if 724 * the header entry is not the correct type. 725 */ 726 sktime_t 727 skHentryPackedfileGetStartTime( 728 const sk_header_entry_t *hentry); 729 730 /** 731 * Return the sensor ID for data in this file. Return 732 * SK_INVALID_SENSOR if header is not the correct type. 733 */ 734 sk_sensor_id_t 735 skHentryPackedfileGetSensorID( 736 const sk_header_entry_t *hentry); 737 738 /** 739 * Return the flowtype for data in this file. Return 740 * SK_INVALID_FLOWTYPE if header is not the correct type. 741 */ 742 sk_flowtype_id_t 743 skHentryPackedfileGetFlowtypeID( 744 const sk_header_entry_t *hentry); 745 746 747 748 /* 749 * ********************************************************************** 750 * 751 * The 'invocation' header entry type is used to store the command 752 * line history, with one 'invocation' structure per command 753 * invocation. 754 * 755 * The current plan is to have one of these per invocation. I 756 * suppose we could think about joining them into a single 757 * header. 758 * 759 * ********************************************************************** 760 */ 761 762 #define SK_HENTRY_INVOCATION_ID 2 763 764 /** 765 * Append a single command line invocation to the header. 766 * 767 * Add the invocation to 'hdr', where 'argc' and 'argv' are the 768 * arguments to main(). If 'strip_path' is non-zero, the basename 769 * of the first value in 'argv' is used. 770 */ 771 int 772 skHeaderAddInvocation( 773 sk_file_header_t *hdr, 774 int strip_path, 775 int argc, 776 char **argv); 777 778 /** 779 * Return the invocation string from this header entry. The caller 780 * must treat the string as read-only. Return NULL if header entry 781 * is the wrong type. Since SiLK 3.17.0. 782 */ 783 const char * 784 skHentryInvocationGetInvocation( 785 const sk_header_entry_t *hentry); 786 787 788 789 /* 790 * ********************************************************************** 791 * 792 * The 'annotation' header entry type is used to store a generic 793 * comment or annotation about the file. 794 * 795 * We should think about making the size of these larger, or have 796 * them allocated in 256 or 512 chunks, so that minor modification 797 * to the annotation can be done on a file without completely 798 * rewriting it. 799 * 800 * ********************************************************************** 801 */ 802 803 #define SK_HENTRY_ANNOTATION_ID 3 804 805 /** 806 * Append a string as a new annotation header. 807 * 808 * Create a new annotation header from the string 'annotation' and 809 * append it to the file header 'hdr'. 810 */ 811 int 812 skHeaderAddAnnotation( 813 sk_file_header_t *hdr, 814 const char *annotation); 815 816 /** 817 * Append a file's contents as a new annotation header. 818 * 819 * Create a new annotation header from the contents of the file 820 * 'pathname' and append it to the file header 'hdr'. 821 */ 822 int 823 skHeaderAddAnnotationFromFile( 824 sk_file_header_t *hdr, 825 const char *pathname); 826 827 /** 828 * Return the annotation string from this header entry. The caller 829 * must treat the string as read-only. Return NULL if header entry 830 * is the wrong type. Since SiLK 3.17.0. 831 */ 832 const char * 833 skHentryAnnotationGetNote( 834 const sk_header_entry_t *hentry); 835 836 837 838 /* 839 * ********************************************************************** 840 * 841 * The 'probename' header entry type is used to store the name of 842 * the probe where flow data was collected. 843 * 844 * flowcap adds this header entry to the files it creates. When 845 * those files are processed by rwflowpack, it reads the probe name 846 * from the header and then searches the sensor.conf file for the 847 * sensor(s) that are able to pack data from that probe. 848 * 849 * ********************************************************************** 850 */ 851 852 #define SK_HENTRY_PROBENAME_ID 4 853 854 /** 855 * Add a header entry containing the name of the probe. 856 */ 857 int 858 skHeaderAddProbename( 859 sk_file_header_t *hdr, 860 const char *probe_name); 861 862 /** 863 * Return the probe name from this header entry. The caller must 864 * treat the string as read-only. Return NULL if header entry is 865 * the wrong type. 866 */ 867 const char * 868 skHentryProbenameGetProbeName( 869 const sk_header_entry_t *hentry); 870 871 872 873 /* 874 * ********************************************************************** 875 * 876 * The 'prefixmap' header entry type is used to store information 877 * particular to prefix maps (pmaps). 878 * 879 * ********************************************************************** 880 */ 881 882 #define SK_HENTRY_PREFIXMAP_ID 5 883 884 885 886 /* 887 * ********************************************************************** 888 * 889 * The 'bag' header entry type is used to store information 890 * particular to binary Bag files. 891 * 892 * ********************************************************************** 893 */ 894 895 #define SK_HENTRY_BAG_ID 6 896 897 898 899 /* 900 * ********************************************************************** 901 * 902 * The 'ipset' header entry type is used to store information 903 * particular to IPSets 904 * 905 * ********************************************************************** 906 */ 907 908 #define SK_HENTRY_IPSET_ID 7 909 910 911 912 /* 913 * ********************************************************************** 914 * 915 * The 'aggbag' header entry type is used to store information 916 * particular to binary Aggregate Bag files. 917 * 918 * ********************************************************************** 919 */ 920 921 #define SK_HENTRY_AGGBAG_ID 8 922 923 924 925 /* 926 * ********************************************************************** 927 * 928 * The 'sidecar' header entry type is used to store information 929 * about additional fields available for each record. 930 * 931 * This is for SiLK 4 and appears here as a placeholder. 932 * 933 * ********************************************************************** 934 */ 935 936 #define SK_HENTRY_SIDECAR_ID 9 937 938 939 940 /* 941 * ********************************************************************** 942 * 943 * The 'tombstone' header entry type stores an identifier from the 944 * YAF or super_mediator process that generated the record. 945 * 946 * ********************************************************************** 947 */ 948 949 #define SK_HENTRY_TOMBSTONE_ID 10 950 951 /** 952 * Append a new tombstone header. 953 * 954 * Create a new tombstone header containing the identifier 955 * 'tombstone_count' and append it to 'hdr'. 956 */ 957 int 958 skHeaderAddTombstone( 959 sk_file_header_t *hdr, 960 uint32_t tombstone_count); 961 962 /** 963 * Return the count value for this tombstone header. Returns 964 * UINT32_MAX if the header is the wrong version. 965 */ 966 uint32_t 967 skHentryTombstoneGetCount( 968 const sk_header_entry_t *hentry); 969 970 971 #ifndef SKHEADER_SOURCE 972 /* Define aliases required for consistency with previous releases of 973 * SiLK. */ 974 975 /** 976 * Replace uses of sk_hentry_packedfile_t with sk_header_entry_t. 977 * Deprecated since SiLK 3.17.0. 978 */ 979 typedef sk_header_entry_t sk_hentry_packedfile_t SK_GCC_DEPRECATED; 980 981 /** 982 * Replace uses of sk_hentry_invocation_t with sk_header_entry_t. 983 * Deprecated since SiLK 3.17.0. 984 */ 985 typedef sk_header_entry_t sk_hentry_probename_t SK_GCC_DEPRECATED; 986 987 #endif /* SKHEADER_SOURCE */ 988 989 990 #ifdef __cplusplus 991 } 992 #endif 993 #endif /* _SKHEADER_H */ 994 995 /* 996 ** Local Variables: 997 ** mode:c 998 ** indent-tabs-mode:nil 999 ** c-basic-offset:4 1000 ** End: 1001 */ 1002