mirror of
https://github.com/michaelrsweet/pdfio.git
synced 2025-07-20 07:49:53 +02:00
Update docos.
This commit is contained in:
Michael R Sweet
@ -728,7 +728,7 @@ password_cb(<span class="reserved">void</span> *data, <span class="reserved">con
|
||||
<span class="reserved">return</span> (<span class="string">"Password42"</span>);
|
||||
}
|
||||
</code></pre>
|
||||
<p>The error callback is called for both errors and warnings and accepts the <code>pdfio_file_t</code> pointer, a message string, and the callback pointer value, for example:</p>
|
||||
<p>The error callback is called for both errors and warnings and accepts the <code>pdfio_file_t</code> pointer, a message string, and the callback pointer value. It returns <code>true</code> to continue processing the file or <code>false</code> to stop, for example:</p>
|
||||
<pre><code class="language-c"><span class="reserved">bool</span>
|
||||
error_cb(pdfio_file_t *pdf, <span class="reserved">const</span> <span class="reserved">char</span> *message, <span class="reserved">void</span> *data)
|
||||
{
|
||||
@ -736,11 +736,14 @@ error_cb(pdfio_file_t *pdf, <span class="reserved">const</span> <span class="res
|
||||
|
||||
fprintf(stderr, <span class="string">"%s: %s\n"</span>, pdfioFileGetName(pdf), message);
|
||||
|
||||
<span class="comment">// Return false to treat warnings as errors</span>
|
||||
<span class="reserved">return</span> (<span class="reserved">false</span>);
|
||||
<span class="comment">// Return true for warning messages (continue) and false for errors (stop)</span>
|
||||
<span class="reserved">return</span> (!strncmp(message, <span class="string">"WARNING:"</span>, <span class="number">8</span>));
|
||||
}
|
||||
</code></pre>
|
||||
<p>The default error callback (<code>NULL</code>) does the equivalent of the above.</p>
|
||||
<blockquote>
|
||||
<p>Note: Many errors are unrecoverable, so PDFio ignores the return value from the error callback and always stops processing the PDF file. Warning messages start with the prefix "WARNING:" while errors have no prefix.</p>
|
||||
</blockquote>
|
||||
<p>Each PDF file contains one or more pages. The <a href="#pdfioFileGetNumPages"><code>pdfioFileGetNumPages</code></a> function returns the number of pages in the file while the <a href="#pdfioFileGetPage"><code>pdfioFileGetPage</code></a> function gets the specified page in the PDF file:</p>
|
||||
<pre><code class="language-c">pdfio_file_t *pdf; <span class="comment">// PDF file</span>
|
||||
size_t i; <span class="comment">// Looping var</span>
|
||||
@ -2746,7 +2749,7 @@ size_t pdfioArrayGetSize(<a href="#pdfio_array_t">pdfio_array_t</a> *a);</p>
|
||||
</tbody></table>
|
||||
<h4 class="returnvalue">Return Value</h4>
|
||||
<p class="description">Value type</p>
|
||||
<h3 class="function"><a id="pdfioArrayRemove">pdfioArrayRemove</a></h3>
|
||||
<h3 class="function"><span class="info"> PDFio v1.4 </span><a id="pdfioArrayRemove">pdfioArrayRemove</a></h3>
|
||||
<p class="description">Remove an array entry.</p>
|
||||
<p class="code">
|
||||
<span class="reserved">bool</span> pdfioArrayRemove(<a href="#pdfio_array_t">pdfio_array_t</a> *a, size_t n);</p>
|
||||
@ -2951,7 +2954,7 @@ using the <a href="#pdfioPageDictAddImage"><code>pdfioPageDictAddImage</code></a
|
||||
</tbody></table>
|
||||
<h4 class="returnvalue">Return Value</h4>
|
||||
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
|
||||
<h3 class="function"><a id="pdfioContentPathEnd">pdfioContentPathEnd</a></h3>
|
||||
<h3 class="function"><span class="info"> PDFio v1.1 </span><a id="pdfioContentPathEnd">pdfioContentPathEnd</a></h3>
|
||||
<p class="description">Clear the current path.</p>
|
||||
<p class="code">
|
||||
<span class="reserved">bool</span> pdfioContentPathEnd(<a href="#pdfio_stream_t">pdfio_stream_t</a> *st);</p>
|
||||
@ -3441,7 +3444,7 @@ are 0, a solid line is drawn.</p>
|
||||
</tbody></table>
|
||||
<h4 class="returnvalue">Return Value</h4>
|
||||
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
|
||||
<h3 class="function"><a id="pdfioContentTextMeasure">pdfioContentTextMeasure</a></h3>
|
||||
<h3 class="function"><span class="info"> PDFio v1.2 </span><a id="pdfioContentTextMeasure">pdfioContentTextMeasure</a></h3>
|
||||
<p class="description">Measure a text string and return its width.</p>
|
||||
<p class="code">
|
||||
<span class="reserved">double</span> pdfioContentTextMeasure(<a href="#pdfio_obj_t">pdfio_obj_t</a> *font, <span class="reserved">const</span> <span class="reserved">char</span> *s, <span class="reserved">double</span> size);</p>
|
||||
@ -3459,7 +3462,9 @@ are 0, a solid line is drawn.</p>
|
||||
<h4 class="discussion">Discussion</h4>
|
||||
<p class="discussion">This function measures the given text string "s" and returns its width based
|
||||
on "size". The text string must always use the UTF-8 (Unicode) encoding but
|
||||
any control characters (such as newlines) are ignored.</p>
|
||||
any control characters (such as newlines) are ignored.
|
||||
|
||||
</p>
|
||||
<h3 class="function"><a id="pdfioContentTextMoveLine">pdfioContentTextMoveLine</a></h3>
|
||||
<p class="description">Move to the next line and offset.</p>
|
||||
<p class="code">
|
||||
@ -3490,7 +3495,7 @@ any control characters (such as newlines) are ignored.</p>
|
||||
</tbody></table>
|
||||
<h4 class="returnvalue">Return Value</h4>
|
||||
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
|
||||
<h3 class="function"><a id="pdfioContentTextNewLine">pdfioContentTextNewLine</a></h3>
|
||||
<h3 class="function"><span class="info"> PDFio v1.2 </span><a id="pdfioContentTextNewLine">pdfioContentTextNewLine</a></h3>
|
||||
<p class="description">Move to the next line.</p>
|
||||
<p class="code">
|
||||
<span class="reserved">bool</span> pdfioContentTextNewLine(<a href="#pdfio_stream_t">pdfio_stream_t</a> *st);</p>
|
||||
@ -3501,7 +3506,7 @@ any control characters (such as newlines) are ignored.</p>
|
||||
</tbody></table>
|
||||
<h4 class="returnvalue">Return Value</h4>
|
||||
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
|
||||
<h3 class="function"><a id="pdfioContentTextNewLineShow">pdfioContentTextNewLineShow</a></h3>
|
||||
<h3 class="function"><span class="info"> PDFio v1.2 </span><a id="pdfioContentTextNewLineShow">pdfioContentTextNewLineShow</a></h3>
|
||||
<p class="description">Move to the next line and show text.</p>
|
||||
<p class="code">
|
||||
<span class="reserved">bool</span> pdfioContentTextNewLineShow(<a href="#pdfio_stream_t">pdfio_stream_t</a> *st, <span class="reserved">double</span> ws, <span class="reserved">double</span> cs, <span class="reserved">bool</span> unicode, <span class="reserved">const</span> <span class="reserved">char</span> *s);</p>
|
||||
@ -3524,8 +3529,10 @@ any control characters (such as newlines) are ignored.</p>
|
||||
<p class="discussion">This function moves to the next line and then shows some text with optional
|
||||
word and character spacing in a PDF content stream. The "unicode" argument
|
||||
specifies that the current font maps to full Unicode. The "s" argument
|
||||
specifies a UTF-8 encoded string.</p>
|
||||
<h3 class="function"><a id="pdfioContentTextNewLineShowf">pdfioContentTextNewLineShowf</a></h3>
|
||||
specifies a UTF-8 encoded string.
|
||||
|
||||
</p>
|
||||
<h3 class="function"><span class="info"> PDFio v1.2 </span><a id="pdfioContentTextNewLineShowf">pdfioContentTextNewLineShowf</a></h3>
|
||||
<p class="description">Show formatted text.</p>
|
||||
<p class="code">
|
||||
<span class="reserved">bool</span> pdfioContentTextNewLineShowf(<a href="#pdfio_stream_t">pdfio_stream_t</a> *st, <span class="reserved">double</span> ws, <span class="reserved">double</span> cs, <span class="reserved">bool</span> unicode, <span class="reserved">const</span> <span class="reserved">char</span> *format, ...);</p>
|
||||
@ -3550,7 +3557,9 @@ specifies a UTF-8 encoded string.</p>
|
||||
<p class="discussion">This function moves to the next line and shows some formatted text with
|
||||
optional word and character spacing in a PDF content stream. The "unicode"
|
||||
argument specifies that the current font maps to full Unicode. The "format"
|
||||
argument specifies a UTF-8 encoded <code>printf</code>-style format string.</p>
|
||||
argument specifies a UTF-8 encoded <code>printf</code>-style format string.
|
||||
|
||||
</p>
|
||||
<h3 class="function"><a id="pdfioContentTextShow">pdfioContentTextShow</a></h3>
|
||||
<p class="description">Show text.</p>
|
||||
<p class="code">
|
||||
@ -3613,7 +3622,7 @@ argument specifies an array of UTF-8 encoded strings.</p>
|
||||
<p class="discussion">This function shows some formatted text in a PDF content stream. The
|
||||
"unicode" argument specifies that the current font maps to full Unicode.
|
||||
The "format" argument specifies a UTF-8 encoded <code>printf</code>-style format string.</p>
|
||||
<h3 class="function"><a id="pdfioDictClear">pdfioDictClear</a></h3>
|
||||
<h3 class="function"><span class="info"> PDFio v1.4 </span><a id="pdfioDictClear">pdfioDictClear</a></h3>
|
||||
<p class="description">Remove a key/value pair from a dictionary.</p>
|
||||
<p class="code">
|
||||
<span class="reserved">bool</span> pdfioDictClear(<a href="#pdfio_dict_t">pdfio_dict_t</a> *dict, <span class="reserved">const</span> <span class="reserved">char</span> *key);</p>
|
||||
@ -3717,7 +3726,7 @@ time_t pdfioDictGetDate(<a href="#pdfio_dict_t">pdfio_dict_t</a> *dict, <span cl
|
||||
</tbody></table>
|
||||
<h4 class="returnvalue">Return Value</h4>
|
||||
<p class="description">Value</p>
|
||||
<h3 class="function"><a id="pdfioDictGetKey">pdfioDictGetKey</a></h3>
|
||||
<h3 class="function"><span class="info"> PDFio v1.4 </span><a id="pdfioDictGetKey">pdfioDictGetKey</a></h3>
|
||||
<p class="description">Get the key for the specified pair.</p>
|
||||
<p class="code">
|
||||
<span class="reserved">const</span> <span class="reserved">char</span> *pdfioDictGetKey(<a href="#pdfio_dict_t">pdfio_dict_t</a> *dict, size_t n);</p>
|
||||
@ -3743,7 +3752,7 @@ time_t pdfioDictGetDate(<a href="#pdfio_dict_t">pdfio_dict_t</a> *dict, <span cl
|
||||
</tbody></table>
|
||||
<h4 class="returnvalue">Return Value</h4>
|
||||
<p class="description">Value</p>
|
||||
<h3 class="function"><a id="pdfioDictGetNumPairs">pdfioDictGetNumPairs</a></h3>
|
||||
<h3 class="function"><span class="info"> PDFio v1.4 </span><a id="pdfioDictGetNumPairs">pdfioDictGetNumPairs</a></h3>
|
||||
<p class="description">Get the number of key/value pairs in a dictionary.</p>
|
||||
<p class="code">
|
||||
size_t pdfioDictGetNumPairs(<a href="#pdfio_dict_t">pdfio_dict_t</a> *dict);</p>
|
||||
@ -3821,7 +3830,7 @@ size_t pdfioDictGetNumPairs(<a href="#pdfio_dict_t">pdfio_dict_t</a> *dict);</p>
|
||||
</tbody></table>
|
||||
<h4 class="returnvalue">Return Value</h4>
|
||||
<p class="description">Value type</p>
|
||||
<h3 class="function"><a id="pdfioDictIterateKeys">pdfioDictIterateKeys</a></h3>
|
||||
<h3 class="function"><span class="info"> PDFio v1.1 </span><a id="pdfioDictIterateKeys">pdfioDictIterateKeys</a></h3>
|
||||
<p class="description">Iterate the keys in a dictionary.</p>
|
||||
<p class="code">
|
||||
<span class="reserved">void</span> pdfioDictIterateKeys(<a href="#pdfio_dict_t">pdfio_dict_t</a> *dict, <a href="#pdfio_dict_cb_t">pdfio_dict_cb_t</a> cb, <span class="reserved">void</span> *cb_data);</p>
|
||||
@ -3848,7 +3857,9 @@ my_dict_cb(pdfio_dict_t *dict, const char *key, void *cb_data)
|
||||
</pre>
|
||||
|
||||
The iteration continues as long as the callback returns <code>true</code> or all keys
|
||||
have been iterated.</p>
|
||||
have been iterated.
|
||||
|
||||
</p>
|
||||
<h3 class="function"><a id="pdfioDictSetArray">pdfioDictSetArray</a></h3>
|
||||
<p class="description">Set a key array in a dictionary.</p>
|
||||
<p class="code">
|
||||
@ -4076,8 +4087,9 @@ CropBox for pages in the PDF file - if <code>NULL</code> then a default "Un
|
||||
of 8.27x11in (the intersection of US Letter and ISO A4) is used.<br>
|
||||
<br>
|
||||
The "error_cb" and "error_cbdata" arguments specify an error handler callback
|
||||
and its data pointer - if <code>NULL</code> the default error handler is used that
|
||||
writes error messages to <code>stderr</code>.</p>
|
||||
and its data pointer - if <code>NULL</code> then the default error handler is used that
|
||||
writes error messages to <code>stderr</code>. The error handler callback should return
|
||||
<code>true</code> to continue writing the PDF file or <code>false</code> to stop.</p>
|
||||
<h3 class="function"><a id="pdfioFileCreateArrayObj">pdfioFileCreateArrayObj</a></h3>
|
||||
<p class="description">Create a new object in a PDF file containing an array.</p>
|
||||
<p class="code">
|
||||
@ -4260,7 +4272,7 @@ image on the page.<br>
|
||||
Note: Currently PNG support is limited to grayscale, RGB, or indexed files
|
||||
without interlacing or alpha. Transparency (masking) based on color/index
|
||||
is supported.</blockquote>
|
||||
<h3 class="function"><a id="pdfioFileCreateNameObj">pdfioFileCreateNameObj</a></h3>
|
||||
<h3 class="function"><span class="info"> PDFio v1.4 </span><a id="pdfioFileCreateNameObj">pdfioFileCreateNameObj</a></h3>
|
||||
<p class="description">Create a new object in a PDF file containing a name.</p>
|
||||
<p class="code">
|
||||
<a href="#pdfio_obj_t">pdfio_obj_t</a> *pdfioFileCreateNameObj(<a href="#pdfio_file_t">pdfio_file_t</a> *pdf, <span class="reserved">const</span> <span class="reserved">char</span> *name);</p>
|
||||
@ -4275,8 +4287,10 @@ is supported.</blockquote>
|
||||
<p class="description">New object</p>
|
||||
<h4 class="discussion">Discussion</h4>
|
||||
<p class="discussion">This function creates a new object with a name value in a PDF file.
|
||||
You must call <a href="#pdfioObjClose"><code>pdfioObjClose</code></a> to write the object to the file.</p>
|
||||
<h3 class="function"><a id="pdfioFileCreateNumberObj">pdfioFileCreateNumberObj</a></h3>
|
||||
You must call <a href="#pdfioObjClose"><code>pdfioObjClose</code></a> to write the object to the file.
|
||||
|
||||
</p>
|
||||
<h3 class="function"><span class="info"> PDFio v1.2 </span><a id="pdfioFileCreateNumberObj">pdfioFileCreateNumberObj</a></h3>
|
||||
<p class="description">Create a new object in a PDF file containing a number.</p>
|
||||
<p class="code">
|
||||
<a href="#pdfio_obj_t">pdfio_obj_t</a> *pdfioFileCreateNumberObj(<a href="#pdfio_file_t">pdfio_file_t</a> *pdf, <span class="reserved">double</span> number);</p>
|
||||
@ -4291,7 +4305,9 @@ You must call <a href="#pdfioObjClose"><code>pdfioObjClose</code></a> to write t
|
||||
<p class="description">New object</p>
|
||||
<h4 class="discussion">Discussion</h4>
|
||||
<p class="discussion">This function creates a new object with a number value in a PDF file.
|
||||
You must call <a href="#pdfioObjClose"><code>pdfioObjClose</code></a> to write the object to the file.</p>
|
||||
You must call <a href="#pdfioObjClose"><code>pdfioObjClose</code></a> to write the object to the file.
|
||||
|
||||
</p>
|
||||
<h3 class="function"><a id="pdfioFileCreateObj">pdfioFileCreateObj</a></h3>
|
||||
<p class="description">Create a new object in a PDF file.</p>
|
||||
<p class="code">
|
||||
@ -4352,8 +4368,9 @@ CropBox for pages in the PDF file - if <code>NULL</code> then a default "Un
|
||||
of 8.27x11in (the intersection of US Letter and ISO A4) is used.<br>
|
||||
<br>
|
||||
The "error_cb" and "error_cbdata" arguments specify an error handler callback
|
||||
and its data pointer - if <code>NULL</code> the default error handler is used that
|
||||
writes error messages to <code>stderr</code>.<br>
|
||||
and its data pointer - if <code>NULL</code> then the default error handler is used that
|
||||
writes error messages to <code>stderr</code>. The error handler callback should return
|
||||
<code>true</code> to continue writing the PDF file or <code>false</code> to stop.<br>
|
||||
<br>
|
||||
</p><blockquote>
|
||||
<em>Note</em>: Files created using this API are slightly larger than those
|
||||
@ -4372,7 +4389,7 @@ stored as indirect object references.</blockquote>
|
||||
</tbody></table>
|
||||
<h4 class="returnvalue">Return Value</h4>
|
||||
<p class="description">Contents stream</p>
|
||||
<h3 class="function"><a id="pdfioFileCreateStringObj">pdfioFileCreateStringObj</a></h3>
|
||||
<h3 class="function"><span class="info"> PDFio v1.2 </span><a id="pdfioFileCreateStringObj">pdfioFileCreateStringObj</a></h3>
|
||||
<p class="description">Create a new object in a PDF file containing a string.</p>
|
||||
<p class="code">
|
||||
<a href="#pdfio_obj_t">pdfio_obj_t</a> *pdfioFileCreateStringObj(<a href="#pdfio_file_t">pdfio_file_t</a> *pdf, <span class="reserved">const</span> <span class="reserved">char</span> *string);</p>
|
||||
@ -4387,7 +4404,9 @@ stored as indirect object references.</blockquote>
|
||||
<p class="description">New object</p>
|
||||
<h4 class="discussion">Discussion</h4>
|
||||
<p class="discussion">This function creates a new object with a string value in a PDF file.
|
||||
You must call <a href="#pdfioObjClose"><code>pdfioObjClose</code></a> to write the object to the file.</p>
|
||||
You must call <a href="#pdfioObjClose"><code>pdfioObjClose</code></a> to write the object to the file.
|
||||
|
||||
</p>
|
||||
<h3 class="function"><a id="pdfioFileCreateTemporary">pdfioFileCreateTemporary</a></h3>
|
||||
<p class="description"></p>
|
||||
<p class="code">
|
||||
@ -4670,8 +4689,15 @@ cancel the open. If <code>NULL</code> is specified for the callback function an
|
||||
PDF file requires a password, the open will always fail.<br>
|
||||
<br>
|
||||
The "error_cb" and "error_cbdata" arguments specify an error handler callback
|
||||
and its data pointer - if <code>NULL</code> the default error handler is used that
|
||||
writes error messages to <code>stderr</code>.</p>
|
||||
and its data pointer - if <code>NULL</code> then the default error handler is used that
|
||||
writes error messages to <code>stderr</code>. The error handler callback should return
|
||||
<code>true</code> to continue reading the PDF file or <code>false</code> to stop.<br>
|
||||
<br>
|
||||
</p><blockquote>
|
||||
Note: Error messages starting with "WARNING:" are actually warning
|
||||
messages - the callback should normally return <code>true</code> to allow PDFio to
|
||||
try to resolve the issue. In addition, some errors are unrecoverable and
|
||||
ignore the return value of the error callback.</blockquote>
|
||||
<h3 class="function"><a id="pdfioFileSetAuthor">pdfioFileSetAuthor</a></h3>
|
||||
<p class="description">Set the author for a PDF file.</p>
|
||||
<p class="code">
|
||||
@ -4892,7 +4918,7 @@ size_t pdfioObjGetLength(<a href="#pdfio_obj_t">pdfio_obj_t</a> *obj);</p>
|
||||
</tbody></table>
|
||||
<h4 class="returnvalue">Return Value</h4>
|
||||
<p class="description">Length in bytes or <code>0</code> for none</p>
|
||||
<h3 class="function"><a id="pdfioObjGetName">pdfioObjGetName</a></h3>
|
||||
<h3 class="function"><span class="info"> PDFio v1.4 </span><a id="pdfioObjGetName">pdfioObjGetName</a></h3>
|
||||
<p class="description">Get the name value associated with an object.</p>
|
||||
<p class="code">
|
||||
<span class="reserved">const</span> <span class="reserved">char</span> *pdfioObjGetName(<a href="#pdfio_obj_t">pdfio_obj_t</a> *obj);</p>
|
||||
@ -5168,8 +5194,9 @@ ssize_t pdfioStreamPeek(<a href="#pdfio_stream_t">pdfio_stream_t</a> *st, <span
|
||||
<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
|
||||
<h4 class="discussion">Discussion</h4>
|
||||
<p class="discussion">This function writes a formatted string to a stream. In addition to the
|
||||
standard <code>printf</code> format characters, you can use "%N" to format a PDF name
|
||||
value ("/Name") and "%S" to format a PDF string ("(String)") value.</p>
|
||||
standard <code>printf</code> format characters, you can use "%H" to format a HTML/XML
|
||||
string value, "%N" to format a PDF name value ("/Name"), and "%S" to format
|
||||
a PDF string ("(String)") value.</p>
|
||||
<h3 class="function"><a id="pdfioStreamPutChar">pdfioStreamPutChar</a></h3>
|
||||
<p class="description">Write a single character to a stream.</p>
|
||||
<p class="code">
|
||||
@ -5403,7 +5430,7 @@ typedef enum <a href="#pdfio_valtype_e">pdfio_valtype_e</a> pdfio_valtype_t;
|
||||
<tr><th>PDFIO_ENCRYPTION_AES_128 </th><td class="description">128-bit AES encryption (PDF 1.6)</td></tr>
|
||||
<tr><th>PDFIO_ENCRYPTION_NONE </th><td class="description">No encryption</td></tr>
|
||||
<tr><th>PDFIO_ENCRYPTION_RC4_128 </th><td class="description">128-bit RC4 encryption (PDF 1.4)</td></tr>
|
||||
<tr><th>PDFIO_ENCRYPTION_RC4_40 </th><td class="description">40-bit RC4 encryption (PDF 1.3)</td></tr>
|
||||
<tr><th>PDFIO_ENCRYPTION_RC4_40 </th><td class="description">40-bit RC4 encryption (PDF 1.3, reading only)</td></tr>
|
||||
</tbody></table>
|
||||
<h3 class="enumeration"><a id="pdfio_filter_e">pdfio_filter_e</a></h3>
|
||||
<p class="description">Compression/decompression filters for streams</p>
|
||||
|
||||
Reference in New Issue
Block a user