Mercurial > libpst

comparison src/libpst.h @ 191:4b498fd68464

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
add pst_attach_to_mem() back into the shared library interface. improve developer documentation. fix memory leak caught by valgrind.
author Carl Byington <carl@five-ten-sg.com>
date Wed, 15 Apr 2009 18:39:42 -0700
parents e3a63888cdd4
children cf3df962f1e5
comparison
equal deleted inserted replaced
190:e3a63888cdd4 191:4b498fd68464
679 /** mapi element 0x8236 PR_OUTLOOK_EVENT_RECURRENCE_END */ 679 /** mapi element 0x8236 PR_OUTLOOK_EVENT_RECURRENCE_END */
680 FILETIME *recurrence_end; 680 FILETIME *recurrence_end;
681 } pst_item_appointment; 681 } pst_item_appointment;
682 682
683 683
684 /** This contains the common mapi elements, and pointers to structures for each major mapi item type */ 684 /** This contains the common mapi elements, and pointers to structures for
685 * each major mapi item type. It represents a complete mapi object.
686 */
685 typedef struct pst_item { 687 typedef struct pst_item {
686 /** email mapi elements */ 688 /** email mapi elements */
687 pst_item_email *email; 689 pst_item_email *email;
688 /** folder mapi elements */ 690 /** folder mapi elements */
689 pst_item_folder *folder; 691 pst_item_folder *folder;
758 * @li 0 false */ 760 * @li 0 false */
759 int private_member; 761 int private_member;
760 } pst_item; 762 } pst_item;
761 763
762 764
763 /** linked list of extended attributes */ 765 /** Linked list of extended attributes.
766 * This is used to convert mapi_id values in the pst file into
767 * cannonical mapi_id values to be used in this code. This list
768 * is kept in sorted order, where the key is the 'map' field.
769 * Some mapi_id values are converted to cannonical mapi_id values
770 * (PST_MAP_ATTRIB), and others are converted to a string
771 * (PST_ATTRIB_HEADER).
772 */
764 typedef struct pst_x_attrib_ll { 773 typedef struct pst_x_attrib_ll {
774 /** obsolete field, this is now unused */
765 uint32_t type; 775 uint32_t type;
776 /** @li 1 PST_MAP_ATTRIB map->int attribute
777 @li 2 PST_MAP_HEADER map->string header
778 */
766 uint32_t mytype; 779 uint32_t mytype;
780 /** key for the mapping */
767 uint32_t map; 781 uint32_t map;
768 void *data; 782 /** data target of the mapping, either uint32_t or string */
783 void *data;
784 /** link to next item in the list */
769 struct pst_x_attrib_ll *next; 785 struct pst_x_attrib_ll *next;
770 } pst_x_attrib_ll; 786 } pst_x_attrib_ll;
771 787
772 788
773 /** this is only used for internal debugging */ 789 /** this is only used for internal debugging */
817 * @li 0x17 64 bit Outlook 2003 or later */ 833 * @li 0x17 64 bit Outlook 2003 or later */
818 unsigned char ind_type; 834 unsigned char ind_type;
819 } pst_file; 835 } pst_file;
820 836
821 837
838 /** Open a pst file.
839 * @param pf pointer to uninitialized pst_file structure. This structure
840 * will be filled in by this function.
841 * @param name name of the file, suitable for fopen().
842 * @return 0 if ok, -1 if error
843 */
822 int pst_open(pst_file *pf, char *name); 844 int pst_open(pst_file *pf, char *name);
845
846
847 /** Load the index entries from the pst file. This loads both the
848 * i_id linked list, and the d_id tree, and should normally be the
849 * first call after pst_open().
850 * @param pf pointer to the pst_file structure setup by pst_open().
851 */
852 int pst_load_index (pst_file *pf);
853
854
855 /** Load the extended attribute mapping table from the pst file. This
856 * should normally be the second call after pst_open().
857 * @param pf pointer to the pst_file structure setup by pst_open().
858 */
859 int pst_load_extended_attributes(pst_file *pf);
860
861
862 /** Close a pst file.
863 * @param pf pointer to the pst_file structure setup by pst_open().
864 */
823 int pst_close(pst_file *pf); 865 int pst_close(pst_file *pf);
866
867
868 /** Get the top of folders descriptor tree. This is the main descriptor tree
869 * that needs to be walked to look at every item in the pst file.
870 * @param pf pointer to the pst_file structure setup by pst_open().
871 * @param root root item, which can be obtained by pst_parse_item(pf, pf->d.head, NULL).
872 */
824 pst_desc_tree* pst_getTopOfFolders(pst_file *pf, pst_item *root); 873 pst_desc_tree* pst_getTopOfFolders(pst_file *pf, pst_item *root);
874
875
876 /** Assemble the binary attachment into a single buffer.
877 * @param pf pointer to the pst_file structure setup by pst_open().
878 * @param attach pointer to the attachment record
879 * @param b pointer to location to store the buffer pointer. The
880 * caller must free this buffer.
881 * @return size of the buffer, and return the buffer pointer in *b
882 */
883 size_t pst_attach_to_mem(pst_file *pf, pst_item_attach *attach, char **b);
884
885
886 /** Write a binary attachment to a file.
887 * @param pf pointer to the pst_file structure setup by pst_open().
888 * @param attach pointer to the attachment record
889 * @param fp pointer to an open FILE.
890 */
825 size_t pst_attach_to_file(pst_file *pf, pst_item_attach *attach, FILE* fp); 891 size_t pst_attach_to_file(pst_file *pf, pst_item_attach *attach, FILE* fp);
892
893
894 /** Write a binary attachment base64 encoded to a file.
895 * @param pf pointer to the pst_file structure setup by pst_open().
896 * @param attach pointer to the attachment record
897 * @param fp pointer to an open FILE.
898 */
826 size_t pst_attach_to_file_base64(pst_file *pf, pst_item_attach *attach, FILE* fp); 899 size_t pst_attach_to_file_base64(pst_file *pf, pst_item_attach *attach, FILE* fp);
827 int pst_load_index (pst_file *pf); 900
901
902 /** Walk the descriptor tree.
903 * @param d pointer to the current item in the descriptor tree.
904 * @return pointer to the next item in the descriptor tree.
905 */
828 pst_desc_tree* pst_getNextDptr(pst_desc_tree* d); 906 pst_desc_tree* pst_getNextDptr(pst_desc_tree* d);
829 int pst_load_extended_attributes(pst_file *pf); 907
830 pst_item* pst_getItem(pst_file *pf, pst_desc_tree *d_ptr); 908
909 /** Assemble a mapi object from a descriptor pointer.
910 * @param pf pointer to the pst_file structure setup by pst_open().
911 * @param d_ptr pointer to an item in the descriptor tree.
912 * @param m_head normally NULL. This is only used when processing embedded
913 * attached rfc822 messages, in which case it is attach->id2_head.
914 * @return pointer to the mapi object. Must be free'd by pst_freeItem().
915 */
831 pst_item* pst_parse_item (pst_file *pf, pst_desc_tree *d_ptr, pst_id2_tree *m_head); 916 pst_item* pst_parse_item (pst_file *pf, pst_desc_tree *d_ptr, pst_id2_tree *m_head);
917
918
919 /** Free the item returned by pst_parse_item().
920 * @param item pointer to item returned from pst_parse_item().
921 */
832 void pst_freeItem(pst_item *item); 922 void pst_freeItem(pst_item *item);
923
924
925 /** Lookup the i_id in the index linked list, and return a pointer to the element.
926 * @param pf pointer to the pst_file structure setup by pst_open().
927 * @param i_id key for the index linked list
928 * @return pointer to the element, or NULL if not found.
929 */
833 pst_index_ll* pst_getID(pst_file* pf, uint64_t i_id); 930 pst_index_ll* pst_getID(pst_file* pf, uint64_t i_id);
834 int pst_decrypt(uint64_t id, char *buf, size_t size, unsigned char type); 931
835 size_t pst_ff_getIDblock_dec(pst_file *pf, uint64_t id, char **b); 932
836 size_t pst_ff_getIDblock(pst_file *pf, uint64_t id, char** b); 933 /** Decrypt a block of data from the pst file.
837 size_t pst_fwrite(const void*ptr, size_t size, size_t nmemb, FILE*stream); 934 * @param i_id identifier of this block, needed as part of the key for the enigma cipher
935 * @param buf pointer to the buffer to be decrypted
936 * @param size size of the buffer
937 * @param type
938 @li 0 PST_NO_ENCRYPT, none
939 @li 1 PST_COMP_ENCRYPT, simple byte substitution cipher with fixed key
940 @li 2 PST_ENCRYPT, german enigma 3 rotor cipher with fixed key
941 * @return 0 if ok, -1 if error (NULL buffer or unknown encryption type)
942 */
943 int pst_decrypt(uint64_t i_id, char *buf, size_t size, unsigned char type);
944
945
946 /** Get an ID block from the file using pst_ff_getIDblock() and decrypt if necessary.
947 * @param pf pointer to the pst_file structure setup by pst_open().
948 * @param i_id ID of block to retrieve
949 * @param buf reference to pointer to buffer that will contain the data block.
950 * If this pointer is non-NULL, it will first be free()d.
951 * @return Size of block read into memory
952 */
953 size_t pst_ff_getIDblock_dec(pst_file *pf, uint64_t i_id, char **buf);
954
955
956 /** Read a block of data from the file into memory.
957 * @param pf pointer to the pst_file structure setup by pst_open().
958 * @param i_id ID of block to read
959 * @param buf reference to pointer to buffer that will contain the data block.
960 * If this pointer is non-NULL, it will first be free()d.
961 * @return size of block read into memory
962 */
963 size_t pst_ff_getIDblock(pst_file *pf, uint64_t i_id, char** buf);
964
965
966 /** fwrite with checking for null pointer.
967 * @param ptr pointer to the buffer
968 * @param size size of each item
969 * @param nmemb number of items
970 * @param stream output file
971 * @return number of bytes written, zero if ptr==NULL
972 */
973 size_t pst_fwrite(const void* ptr, size_t size, size_t nmemb, FILE* stream);
974
975
976 /** Add any necessary escape characters for rfc2426 vcard format
977 * @param str pointer to input string
978 * @return pointer to output string, either the input pointer if
979 * there are no characters that need escapes, or a pointer
980 * to a different buffer containing the escaped string. In
981 * either case, you don't need to free this returned pointer.
982 */
838 char * pst_rfc2426_escape(char *str); 983 char * pst_rfc2426_escape(char *str);
984
985
986 /** Convert a FILETIME into rfc2425 date/time format 1953-10-15T23:10:00Z
987 * which is the same as one of the forms in the ISO3601 standard
988 * @param ft time to be converted
989 * @return time in rfc2425 format
990 */
839 char * pst_rfc2425_datetime_format(FILETIME *ft); 991 char * pst_rfc2425_datetime_format(FILETIME *ft);
992
993
994 /** Convert a FILETIME into rfc2445 date/time format 19531015T231000Z
995 * @param ft time to be converted
996 * @return time in rfc2445 format
997 */
840 char * pst_rfc2445_datetime_format(FILETIME *ft); 998 char * pst_rfc2445_datetime_format(FILETIME *ft);
841 999
842 1000
843 /** Convert a code page integer into a string suitable for iconv() 1001 /** Convert a code page integer into a string suitable for iconv()
844 * 1002 * @param cp the code page integer used in the pst file
845 * @param cp the code page integer used in the pst file
846 * @return pointer to a static buffer holding the string representation of the 1003 * @return pointer to a static buffer holding the string representation of the
847 * equivalent iconv character set 1004 * equivalent iconv character set
848 */ 1005 */
849 const char* pst_codepage(int cp); 1006 const char* pst_codepage(int cp);
850 1007
856 */ 1013 */
857 const char* pst_default_charset(pst_item *item); 1014 const char* pst_default_charset(pst_item *item);
858 1015
859 1016
860 /** Convert str to utf8 if possible; null strings are preserved. 1017 /** Convert str to utf8 if possible; null strings are preserved.
861 *
862 * @param item pointer to the containing mapi item 1018 * @param item pointer to the containing mapi item
863 * @param str pointer to the mapi string of interest 1019 * @param str pointer to the mapi string of interest
864 */ 1020 */
865 void pst_convert_utf8_null(pst_item *item, pst_string *str); 1021 void pst_convert_utf8_null(pst_item *item, pst_string *str);
866 1022
867 1023
868 /** Convert str to utf8 if possible; null strings are converted into empty strings. 1024 /** Convert str to utf8 if possible; null strings are converted into empty strings.
869 *
870 * @param item pointer to the containing mapi item 1025 * @param item pointer to the containing mapi item
871 * @param str pointer to the mapi string of interest 1026 * @param str pointer to the mapi string of interest
872 */ 1027 */
873 void pst_convert_utf8(pst_item *item, pst_string *str); 1028 void pst_convert_utf8(pst_item *item, pst_string *str);
874 1029