1 // Copyright 2017 The PDFium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef PUBLIC_FPDF_ATTACHMENT_H_ 6 #define PUBLIC_FPDF_ATTACHMENT_H_ 7 8 // NOLINTNEXTLINE(build/include) 9 #include "fpdfview.h" 10 11 #ifdef __cplusplus 12 extern "C" { 13 #endif // __cplusplus 14 15 // Experimental API. 16 // Get the number of embedded files in |document|. 17 // 18 // document - handle to a document. 19 // 20 // Returns the number of embedded files in |document|. 21 FPDF_EXPORT int FPDF_CALLCONV 22 FPDFDoc_GetAttachmentCount(FPDF_DOCUMENT document); 23 24 // Experimental API. 25 // Add an embedded file with |name| in |document|. If |name| is empty, or if 26 // |name| is the name of a existing embedded file in |document|, or if 27 // |document|'s embedded file name tree is too deep (i.e. |document| has too 28 // many embedded files already), then a new attachment will not be added. 29 // 30 // document - handle to a document. 31 // name - name of the new attachment. 32 // 33 // Returns a handle to the new attachment object, or NULL on failure. 34 FPDF_EXPORT FPDF_ATTACHMENT FPDF_CALLCONV 35 FPDFDoc_AddAttachment(FPDF_DOCUMENT document, FPDF_WIDESTRING name); 36 37 // Experimental API. 38 // Get the embedded attachment at |index| in |document|. Note that the returned 39 // attachment handle is only valid while |document| is open. 40 // 41 // document - handle to a document. 42 // index - the index of the requested embedded file. 43 // 44 // Returns the handle to the attachment object, or NULL on failure. 45 FPDF_EXPORT FPDF_ATTACHMENT FPDF_CALLCONV 46 FPDFDoc_GetAttachment(FPDF_DOCUMENT document, int index); 47 48 // Experimental API. 49 // Delete the embedded attachment at |index| in |document|. Note that this does 50 // not remove the attachment data from the PDF file; it simply removes the 51 // file's entry in the embedded files name tree so that it does not appear in 52 // the attachment list. This behavior may change in the future. 53 // 54 // document - handle to a document. 55 // index - the index of the embedded file to be deleted. 56 // 57 // Returns true if successful. 58 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 59 FPDFDoc_DeleteAttachment(FPDF_DOCUMENT document, int index); 60 61 // Experimental API. 62 // Get the name of the |attachment| file. |buffer| is only modified if |buflen| 63 // is longer than the length of the file name. On errors, |buffer| is unmodified 64 // and the returned length is 0. 65 // 66 // attachment - handle to an attachment. 67 // buffer - buffer for holding the file name, encoded in UTF-16LE. 68 // buflen - length of the buffer in bytes. 69 // 70 // Returns the length of the file name in bytes. 71 FPDF_EXPORT unsigned long FPDF_CALLCONV 72 FPDFAttachment_GetName(FPDF_ATTACHMENT attachment, 73 FPDF_WCHAR* buffer, 74 unsigned long buflen); 75 76 // Experimental API. 77 // Check if the params dictionary of |attachment| has |key| as a key. 78 // 79 // attachment - handle to an attachment. 80 // key - the key to look for, encoded in UTF-8. 81 // 82 // Returns true if |key| exists. 83 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 84 FPDFAttachment_HasKey(FPDF_ATTACHMENT attachment, FPDF_BYTESTRING key); 85 86 // Experimental API. 87 // Get the type of the value corresponding to |key| in the params dictionary of 88 // the embedded |attachment|. 89 // 90 // attachment - handle to an attachment. 91 // key - the key to look for, encoded in UTF-8. 92 // 93 // Returns the type of the dictionary value. 94 FPDF_EXPORT FPDF_OBJECT_TYPE FPDF_CALLCONV 95 FPDFAttachment_GetValueType(FPDF_ATTACHMENT attachment, FPDF_BYTESTRING key); 96 97 // Experimental API. 98 // Set the string value corresponding to |key| in the params dictionary of the 99 // embedded file |attachment|, overwriting the existing value if any. The value 100 // type should be FPDF_OBJECT_STRING after this function call succeeds. 101 // 102 // attachment - handle to an attachment. 103 // key - the key to the dictionary entry, encoded in UTF-8. 104 // value - the string value to be set, encoded in UTF-16LE. 105 // 106 // Returns true if successful. 107 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 108 FPDFAttachment_SetStringValue(FPDF_ATTACHMENT attachment, 109 FPDF_BYTESTRING key, 110 FPDF_WIDESTRING value); 111 112 // Experimental API. 113 // Get the string value corresponding to |key| in the params dictionary of the 114 // embedded file |attachment|. |buffer| is only modified if |buflen| is longer 115 // than the length of the string value. Note that if |key| does not exist in the 116 // dictionary or if |key|'s corresponding value in the dictionary is not a 117 // string (i.e. the value is not of type FPDF_OBJECT_STRING or 118 // FPDF_OBJECT_NAME), then an empty string would be copied to |buffer| and the 119 // return value would be 2. On other errors, nothing would be added to |buffer| 120 // and the return value would be 0. 121 // 122 // attachment - handle to an attachment. 123 // key - the key to the requested string value, encoded in UTF-8. 124 // buffer - buffer for holding the string value encoded in UTF-16LE. 125 // buflen - length of the buffer in bytes. 126 // 127 // Returns the length of the dictionary value string in bytes. 128 FPDF_EXPORT unsigned long FPDF_CALLCONV 129 FPDFAttachment_GetStringValue(FPDF_ATTACHMENT attachment, 130 FPDF_BYTESTRING key, 131 FPDF_WCHAR* buffer, 132 unsigned long buflen); 133 134 // Experimental API. 135 // Set the file data of |attachment|, overwriting the existing file data if any. 136 // The creation date and checksum will be updated, while all other dictionary 137 // entries will be deleted. Note that only contents with |len| smaller than 138 // INT_MAX is supported. 139 // 140 // attachment - handle to an attachment. 141 // contents - buffer holding the file data to write to |attachment|. 142 // len - length of file data in bytes. 143 // 144 // Returns true if successful. 145 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 146 FPDFAttachment_SetFile(FPDF_ATTACHMENT attachment, 147 FPDF_DOCUMENT document, 148 const void* contents, 149 unsigned long len); 150 151 // Experimental API. 152 // Get the file data of |attachment|. 153 // When the attachment file data is readable, true is returned, and |out_buflen| 154 // is updated to indicate the file data size. |buffer| is only modified if 155 // |buflen| is non-null and long enough to contain the entire file data. Callers 156 // must check both the return value and the input |buflen| is no less than the 157 // returned |out_buflen| before using the data. 158 // 159 // Otherwise, when the attachment file data is unreadable or when |out_buflen| 160 // is null, false is returned and |buffer| and |out_buflen| remain unmodified. 161 // 162 // attachment - handle to an attachment. 163 // buffer - buffer for holding the file data from |attachment|. 164 // buflen - length of the buffer in bytes. 165 // out_buflen - pointer to the variable that will receive the minimum buffer 166 // size to contain the file data of |attachment|. 167 // 168 // Returns true on success, false otherwise. 169 FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV 170 FPDFAttachment_GetFile(FPDF_ATTACHMENT attachment, 171 void* buffer, 172 unsigned long buflen, 173 unsigned long* out_buflen); 174 175 #ifdef __cplusplus 176 } // extern "C" 177 #endif // __cplusplus 178 179 #endif // PUBLIC_FPDF_ATTACHMENT_H_ 180