1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
3 <!-- SECTION: Programming -->
5 <title>MIME API
</title>
6 <meta name=
"keywords" content=
"Programming">
7 <meta http-equiv=
"Content-Type" content=
"text/html;charset=utf-8">
8 <meta name=
"creator" content=
"Mini-XML v2.7">
9 <style type=
"text/css"><!--
11 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
14 H1, H2, H3, H4, H5, H6, P, TD, TH {
15 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
19 font-family: monaco, courier, monospace;
24 font-family: monaco, courier, monospace;
28 border: dotted thin #7f7f7f;
56 border: dotted thin #999999;
61 PRE.command EM, PRE.example EM {
62 font-family: lucida grande, geneva, helvetica, arial, sans-serif;
66 font-family: monaco, courier, monospace;
77 border: solid thin #999999;
88 -moz-border-radius: 10px;
93 text-decoration: none;
96 A:link:hover, A:visited:hover, A:active {
97 text-decoration: underline;
104 TR.data, TD.data, TR.data TD {
107 border-bottom: solid 1pt #999999;
111 border-bottom: solid 1pt #999999;
118 border: solid thin #999999;
119 border-collapse: collapse;
135 border: solid thin #cccccc;
142 border-bottom: solid thin #999999;
151 caption-side: bottom;
175 border: thin solid black;
183 H2 SPAN.info, H3 SPAN.info, H4 SPAN.info {
192 border-bottom: solid 2pt #000000;
195 DIV.indent, TABLE.indent {
203 border-collapse: collapse;
206 TABLE.indent TD, TABLE.indent TH {
211 border-collapse: collapse;
219 border-bottom: solid thin #cccccc;
224 vertical-align: bottom;
233 border-bottom: solid thin #eeeeee;
238 TABLE.list TR:nth-child(even) {
242 TABLE.list TR:nth-child(odd) {
261 font-family: monaco, courier, monospace;
265 border: solid thin #999999;
266 border-collapse: collapse;
271 DIV.summary TABLE TD, DIV.summary TABLE TH {
272 border: solid thin #999999;
278 DIV.summary TABLE THEAD TH {
282 /* API documentation styles... */
289 div.body h3, div.body h4, div.body h5 {
290 margin-bottom: 0.5em;
293 .class, .enumeration, .function, .struct, .typedef, .union {
294 border-bottom: solid thin #999999;
301 code, p.code, pre, ul.code li {
302 font-family: monaco, courier, monospace;
305 ul.code, ul.contents, ul.subcontents {
306 list-style-type: none;
316 ul.contents li ul.code, ul.contents li ul.subcontents {
329 margin-bottom: 0.5em;
332 /* This is just for the HTML files generated with the framedhelp target */
335 border: solid thin black;
344 div.contents ul.contents {
347 div.contents ul.subcontents li {
356 "$Id: api-array.header 8087 2008-10-27 21:37:05Z mike $"
358 MIME API header for CUPS.
360 Copyright 2009 by Apple Inc.
362 These coded instructions, statements, and computer programs are the
363 property of Apple Inc. and are protected by Federal copyright
364 law. Distribution and use rights are outlined in the file "LICENSE.txt"
365 which should have been included with this file. If this file is
366 file is missing or damaged, see the license at "http://www.cups.org/".
369 <h1 class='title'
>MIME API
</h1>
371 <div class='summary'
><table summary='General Information'
>
385 <td>Programming:
<a href='api-overview.html' target='_top'
>Introduction to CUPS Programming
</a></td>
389 <h2 class=
"title">Contents
</h2>
390 <ul class=
"contents">
391 <li><a href=
"#OVERVIEW">Overview
</a></li>
392 <li><a href=
"#FUNCTIONS">Functions
</a><ul class=
"code">
393 <li><a href=
"#mimeAddFilter" title=
"Add a filter to the current MIME database.">mimeAddFilter
</a></li>
394 <li><a href=
"#mimeAddType" title=
"Add a MIME type to a database.">mimeAddType
</a></li>
395 <li><a href=
"#mimeAddTypeRule" title=
"Add a detection rule for a file type.">mimeAddTypeRule
</a></li>
396 <li><a href=
"#mimeDelete" title=
"Delete (free) a MIME database.">mimeDelete
</a></li>
397 <li><a href=
"#mimeDeleteFilter" title=
"Delete a filter from the MIME database.">mimeDeleteFilter
</a></li>
398 <li><a href=
"#mimeDeleteType" title=
"Delete a type from the MIME database.">mimeDeleteType
</a></li>
399 <li><a href=
"#mimeFileType" title=
"Determine the type of a file.">mimeFileType
</a></li>
400 <li><a href=
"#mimeFilter" title=
"Find the fastest way to convert from one type to another.">mimeFilter
</a></li>
401 <li><a href=
"#mimeFilter2" title=
"Find the fastest way to convert from one type to another,
402 including file size.">mimeFilter2
</a></li>
403 <li><a href=
"#mimeFilterLookup" title=
"Lookup a filter.">mimeFilterLookup
</a></li>
404 <li><a href=
"#mimeFirstFilter" title=
"Get the first filter in the MIME database.">mimeFirstFilter
</a></li>
405 <li><a href=
"#mimeFirstType" title=
"Get the first type in the MIME database.">mimeFirstType
</a></li>
406 <li><a href=
"#mimeLoad" title=
"Create a new MIME database from disk.">mimeLoad
</a></li>
407 <li><a href=
"#mimeLoadFilters" title=
"Load filter definitions from disk.">mimeLoadFilters
</a></li>
408 <li><a href=
"#mimeLoadTypes" title=
"Load type definitions from disk.">mimeLoadTypes
</a></li>
409 <li><a href=
"#mimeNew" title=
"Create a new, empty MIME database.">mimeNew
</a></li>
410 <li><a href=
"#mimeNextFilter" title=
"Get the next filter in the MIME database.">mimeNextFilter
</a></li>
411 <li><a href=
"#mimeNextType" title=
"Get the next type in the MIME database.">mimeNextType
</a></li>
412 <li><a href=
"#mimeNumFilters" title=
"Next type">mimeNumFilters
</a></li>
413 <li><a href=
"#mimeNumTypes" title=
"MIME database">mimeNumTypes
</a></li>
414 <li><a href=
"#mimeSetErrorCallback" title=
"Set the callback for error messages.">mimeSetErrorCallback
</a></li>
415 <li><a href=
"#mimeType" title=
"Lookup a file type.">mimeType
</a></li>
417 <li><a href=
"#TYPES">Data Types
</a><ul class=
"code">
418 <li><a href=
"#const" title=
"MIME Database">const
</a></li>
419 <li><a href=
"#mime_filter_t" title=
"MIME Conversion Filter Data">mime_filter_t
</a></li>
420 <li><a href=
"#mime_magic_t" title=
"MIME Magic Data">mime_magic_t
</a></li>
421 <li><a href=
"#mime_op_t" title=
"Types/structures...">mime_op_t
</a></li>
422 <li><a href=
"#mime_t" title=
"MIME Database">mime_t
</a></li>
423 <li><a href=
"#mime_type_t" title=
"MIME Type Data">mime_type_t
</a></li>
427 "$Id: api-array.shtml 7616 2008-05-28 00:34:13Z mike $"
429 MIME API introduction for CUPS.
431 Copyright 2009 by Apple Inc.
433 These coded instructions, statements, and computer programs are the
434 property of Apple Inc. and are protected by Federal copyright
435 law. Distribution and use rights are outlined in the file "LICENSE.txt"
436 which should have been included with this file. If this file is
437 file is missing or damaged, see the license at "http://www.cups.org/".
440 <h2 class='title'
><a name='OVERVIEW'
>Overview
</a></h2>
442 <p>The MIME API provides file typing and conversion services for CUPS.
</p>
443 <h2 class=
"title"><a name=
"FUNCTIONS">Functions
</a></h2>
444 <h3 class=
"function"><a name=
"mimeAddFilter">mimeAddFilter
</a></h3>
445 <p class=
"description">Add a filter to the current MIME database.
</p>
447 <a href=
"#mime_filter_t">mime_filter_t
</a> *mimeAddFilter (
<br>
448 <a href=
"#mime_t">mime_t
</a> *mime,
<br>
449 <a href=
"#mime_type_t">mime_type_t
</a> *src,
<br>
450 <a href=
"#mime_type_t">mime_type_t
</a> *dst,
<br>
451 int cost,
<br>
452 <a href=
"#const">const
</a> char *filter
<br>
454 <h4 class=
"parameters">Parameters
</h4>
457 <dd class=
"description">MIME database
</dd>
459 <dd class=
"description">Source type
</dd>
461 <dd class=
"description">Destination type
</dd>
463 <dd class=
"description">Relative time/resource cost
</dd>
465 <dd class=
"description">Filter program to run
</dd>
467 <h4 class=
"returnvalue">Return Value
</h4>
468 <p class=
"description">New filter
</p>
469 <h3 class=
"function"><a name=
"mimeAddType">mimeAddType
</a></h3>
470 <p class=
"description">Add a MIME type to a database.
</p>
472 <a href=
"#mime_type_t">mime_type_t
</a> *mimeAddType (
<br>
473 <a href=
"#mime_t">mime_t
</a> *mime,
<br>
474 <a href=
"#const">const
</a> char *super,
<br>
475 <a href=
"#const">const
</a> char *type
<br>
477 <h4 class=
"parameters">Parameters
</h4>
480 <dd class=
"description">MIME database
</dd>
482 <dd class=
"description">Super-type name
</dd>
484 <dd class=
"description">Type name
</dd>
486 <h4 class=
"returnvalue">Return Value
</h4>
487 <p class=
"description">New (or existing) MIME type
</p>
488 <h3 class=
"function"><a name=
"mimeAddTypeRule">mimeAddTypeRule
</a></h3>
489 <p class=
"description">Add a detection rule for a file type.
</p>
491 int mimeAddTypeRule (
<br>
492 <a href=
"#mime_type_t">mime_type_t
</a> *mt,
<br>
493 <a href=
"#const">const
</a> char *rule
<br>
495 <h4 class=
"parameters">Parameters
</h4>
498 <dd class=
"description">Type to add to
</dd>
500 <dd class=
"description">Rule to add
</dd>
502 <h4 class=
"returnvalue">Return Value
</h4>
503 <p class=
"description">0 on success, -
1 on failure
</p>
504 <h3 class=
"function"><a name=
"mimeDelete">mimeDelete
</a></h3>
505 <p class=
"description">Delete (free) a MIME database.
</p>
507 void mimeDelete (
<br>
508 <a href=
"#mime_t">mime_t
</a> *mime
<br>
510 <h4 class=
"parameters">Parameters
</h4>
513 <dd class=
"description">MIME database
</dd>
515 <h3 class=
"function"><a name=
"mimeDeleteFilter">mimeDeleteFilter
</a></h3>
516 <p class=
"description">Delete a filter from the MIME database.
</p>
518 void mimeDeleteFilter (
<br>
519 <a href=
"#mime_t">mime_t
</a> *mime,
<br>
520 <a href=
"#mime_filter_t">mime_filter_t
</a> *filter
<br>
522 <h4 class=
"parameters">Parameters
</h4>
525 <dd class=
"description">MIME database
</dd>
527 <dd class=
"description">Filter
</dd>
529 <h3 class=
"function"><a name=
"mimeDeleteType">mimeDeleteType
</a></h3>
530 <p class=
"description">Delete a type from the MIME database.
</p>
532 void mimeDeleteType (
<br>
533 <a href=
"#mime_t">mime_t
</a> *mime,
<br>
534 <a href=
"#mime_type_t">mime_type_t
</a> *mt
<br>
536 <h4 class=
"parameters">Parameters
</h4>
539 <dd class=
"description">MIME database
</dd>
541 <dd class=
"description">Type
</dd>
543 <h3 class=
"function"><a name=
"mimeFileType">mimeFileType
</a></h3>
544 <p class=
"description">Determine the type of a file.
</p>
546 <a href=
"#mime_type_t">mime_type_t
</a> *mimeFileType (
<br>
547 <a href=
"#mime_t">mime_t
</a> *mime,
<br>
548 <a href=
"#const">const
</a> char *pathname,
<br>
549 <a href=
"#const">const
</a> char *filename,
<br>
550 int *compression
<br>
552 <h4 class=
"parameters">Parameters
</h4>
555 <dd class=
"description">MIME database
</dd>
557 <dd class=
"description">Name of file to check on disk
</dd>
559 <dd class=
"description">Original filename or NULL
</dd>
561 <dd class=
"description">Is the file compressed?
</dd>
563 <h4 class=
"returnvalue">Return Value
</h4>
564 <p class=
"description">Type of file
</p>
565 <h3 class=
"function"><a name=
"mimeFilter">mimeFilter
</a></h3>
566 <p class=
"description">Find the fastest way to convert from one type to another.
</p>
568 cups_array_t *mimeFilter (
<br>
569 <a href=
"#mime_t">mime_t
</a> *mime,
<br>
570 <a href=
"#mime_type_t">mime_type_t
</a> *src,
<br>
571 <a href=
"#mime_type_t">mime_type_t
</a> *dst,
<br>
572 int *cost
<br>
574 <h4 class=
"parameters">Parameters
</h4>
577 <dd class=
"description">MIME database
</dd>
579 <dd class=
"description">Source file type
</dd>
581 <dd class=
"description">Destination file type
</dd>
583 <dd class=
"description">Cost of filters
</dd>
585 <h4 class=
"returnvalue">Return Value
</h4>
586 <p class=
"description">Array of filters to run
</p>
587 <h3 class=
"function"><a name=
"mimeFilter2">mimeFilter2
</a></h3>
588 <p class=
"description">Find the fastest way to convert from one type to another,
589 including file size.
</p>
591 cups_array_t *mimeFilter2 (
<br>
592 <a href=
"#mime_t">mime_t
</a> *mime,
<br>
593 <a href=
"#mime_type_t">mime_type_t
</a> *src,
<br>
594 size_t srcsize,
<br>
595 <a href=
"#mime_type_t">mime_type_t
</a> *dst,
<br>
596 int *cost
<br>
598 <h4 class=
"parameters">Parameters
</h4>
601 <dd class=
"description">MIME database
</dd>
603 <dd class=
"description">Source file type
</dd>
605 <dd class=
"description">Size of source file
</dd>
607 <dd class=
"description">Destination file type
</dd>
609 <dd class=
"description">Cost of filters
</dd>
611 <h4 class=
"returnvalue">Return Value
</h4>
612 <p class=
"description">Array of filters to run
</p>
613 <h3 class=
"function"><a name=
"mimeFilterLookup">mimeFilterLookup
</a></h3>
614 <p class=
"description">Lookup a filter.
</p>
616 <a href=
"#mime_filter_t">mime_filter_t
</a> *mimeFilterLookup (
<br>
617 <a href=
"#mime_t">mime_t
</a> *mime,
<br>
618 <a href=
"#mime_type_t">mime_type_t
</a> *src,
<br>
619 <a href=
"#mime_type_t">mime_type_t
</a> *dst
<br>
621 <h4 class=
"parameters">Parameters
</h4>
624 <dd class=
"description">MIME database
</dd>
626 <dd class=
"description">Source type
</dd>
628 <dd class=
"description">Destination type
</dd>
630 <h4 class=
"returnvalue">Return Value
</h4>
631 <p class=
"description">Filter for src-
>dst
</p>
632 <h3 class=
"function"><a name=
"mimeFirstFilter">mimeFirstFilter
</a></h3>
633 <p class=
"description">Get the first filter in the MIME database.
</p>
635 <a href=
"#mime_filter_t">mime_filter_t
</a> *mimeFirstFilter (
<br>
636 <a href=
"#mime_t">mime_t
</a> *mime
<br>
638 <h4 class=
"parameters">Parameters
</h4>
641 <dd class=
"description">MIME database
</dd>
643 <h4 class=
"returnvalue">Return Value
</h4>
644 <p class=
"description">Filter or NULL
</p>
645 <h3 class=
"function"><a name=
"mimeFirstType">mimeFirstType
</a></h3>
646 <p class=
"description">Get the first type in the MIME database.
</p>
648 <a href=
"#mime_type_t">mime_type_t
</a> *mimeFirstType (
<br>
649 <a href=
"#mime_t">mime_t
</a> *mime
<br>
651 <h4 class=
"parameters">Parameters
</h4>
654 <dd class=
"description">MIME database
</dd>
656 <h4 class=
"returnvalue">Return Value
</h4>
657 <p class=
"description">Type or NULL
</p>
658 <h3 class=
"function"><a name=
"mimeLoad">mimeLoad
</a></h3>
659 <p class=
"description">Create a new MIME database from disk.
</p>
661 <a href=
"#mime_t">mime_t
</a> *mimeLoad (
<br>
662 <a href=
"#const">const
</a> char *pathname,
<br>
663 <a href=
"#const">const
</a> char *filterpath
<br>
665 <h4 class=
"parameters">Parameters
</h4>
668 <dd class=
"description">Directory to load
</dd>
670 <dd class=
"description">Directory to load
</dd>
672 <h4 class=
"returnvalue">Return Value
</h4>
673 <p class=
"description">New MIME database
</p>
674 <h4 class=
"discussion">Discussion
</h4>
675 <p class=
"discussion">This function uses
<a href=
"#mimeLoadFilters"><code>mimeLoadFilters
</code></a> and
<a href=
"#mimeLoadTypes"><code>mimeLoadTypes
</code></a> to
676 create a MIME database from a single directory.
</p>
677 <h3 class=
"function"><a name=
"mimeLoadFilters">mimeLoadFilters
</a></h3>
678 <p class=
"description">Load filter definitions from disk.
</p>
680 <a href=
"#mime_t">mime_t
</a> *mimeLoadFilters (
<br>
681 <a href=
"#mime_t">mime_t
</a> *mime,
<br>
682 <a href=
"#const">const
</a> char *pathname,
<br>
683 <a href=
"#const">const
</a> char *filterpath
<br>
685 <h4 class=
"parameters">Parameters
</h4>
688 <dd class=
"description">MIME database
</dd>
690 <dd class=
"description">Directory to load from
</dd>
692 <dd class=
"description">Default filter program directory
</dd>
694 <h4 class=
"returnvalue">Return Value
</h4>
695 <p class=
"description">MIME database
</p>
696 <h4 class=
"discussion">Discussion
</h4>
697 <p class=
"discussion">This function loads all of the .convs files from the specified directory.
698 Use
<a href=
"#mimeLoadTypes"><code>mimeLoadTypes
</code></a> to load all types before you load the filters.
</p>
699 <h3 class=
"function"><a name=
"mimeLoadTypes">mimeLoadTypes
</a></h3>
700 <p class=
"description">Load type definitions from disk.
</p>
702 <a href=
"#mime_t">mime_t
</a> *mimeLoadTypes (
<br>
703 <a href=
"#mime_t">mime_t
</a> *mime,
<br>
704 <a href=
"#const">const
</a> char *pathname
<br>
706 <h4 class=
"parameters">Parameters
</h4>
709 <dd class=
"description">MIME database or
<code>NULL
</code> to create a new one
</dd>
711 <dd class=
"description">Directory to load from
</dd>
713 <h4 class=
"returnvalue">Return Value
</h4>
714 <p class=
"description">MIME database
</p>
715 <h4 class=
"discussion">Discussion
</h4>
716 <p class=
"discussion">This function loads all of the .types files from the specified directory.
717 Use
<a href=
"#mimeLoadFilters"><code>mimeLoadFilters
</code></a> to load all filters after you load the types.
</p>
718 <h3 class=
"function"><a name=
"mimeNew">mimeNew
</a></h3>
719 <p class=
"description">Create a new, empty MIME database.
</p>
721 <a href=
"#mime_t">mime_t
</a> *mimeNew (void);
</p>
722 <h4 class=
"returnvalue">Return Value
</h4>
723 <p class=
"description">MIME database
</p>
724 <h3 class=
"function"><a name=
"mimeNextFilter">mimeNextFilter
</a></h3>
725 <p class=
"description">Get the next filter in the MIME database.
</p>
727 <a href=
"#mime_filter_t">mime_filter_t
</a> *mimeNextFilter (
<br>
728 <a href=
"#mime_t">mime_t
</a> *mime
<br>
730 <h4 class=
"parameters">Parameters
</h4>
733 <dd class=
"description">MIME database
</dd>
735 <h4 class=
"returnvalue">Return Value
</h4>
736 <p class=
"description">Filter or NULL
</p>
737 <h3 class=
"function"><a name=
"mimeNextType">mimeNextType
</a></h3>
738 <p class=
"description">Get the next type in the MIME database.
</p>
740 <a href=
"#mime_type_t">mime_type_t
</a> *mimeNextType (
<br>
741 <a href=
"#mime_t">mime_t
</a> *mime
<br>
743 <h4 class=
"parameters">Parameters
</h4>
746 <dd class=
"description">MIME database
</dd>
748 <h4 class=
"returnvalue">Return Value
</h4>
749 <p class=
"description">Type or NULL
</p>
750 <h3 class=
"function"><a name=
"mimeNumFilters">mimeNumFilters
</a></h3>
751 <p class=
"description">Next type
</p>
753 int mimeNumFilters (
<br>
754 <a href=
"#mime_t">mime_t
</a> *mime
<br>
756 <h4 class=
"parameters">Parameters
</h4>
759 <dd class=
"description">MIME database
</dd>
761 <h4 class=
"returnvalue">Return Value
</h4>
762 <p class=
"description">Get the number of filters in a MIME database.
</p>
763 <h3 class=
"function"><a name=
"mimeNumTypes">mimeNumTypes
</a></h3>
764 <p class=
"description">MIME database
</p>
766 int mimeNumTypes (
<br>
767 <a href=
"#mime_t">mime_t
</a> *mime
<br>
769 <h4 class=
"parameters">Parameters
</h4>
772 <dd class=
"description">MIME database
</dd>
774 <h4 class=
"returnvalue">Return Value
</h4>
775 <p class=
"description">Get the number of types in a MIME database.
</p>
776 <h3 class=
"function"><a name=
"mimeSetErrorCallback">mimeSetErrorCallback
</a></h3>
777 <p class=
"description">Set the callback for error messages.
</p>
779 void mimeSetErrorCallback (
<br>
780 <a href=
"#mime_t">mime_t
</a> *mime,
<br>
781 mime_error_cb_t cb,
<br>
782 void *ctx
<br>
784 <h4 class=
"parameters">Parameters
</h4>
787 <dd class=
"description">MIME database
</dd>
789 <dd class=
"description">Callback function
</dd>
791 <dd class=
"description">Context pointer for callback
</dd>
793 <h3 class=
"function"><a name=
"mimeType">mimeType
</a></h3>
794 <p class=
"description">Lookup a file type.
</p>
796 <a href=
"#mime_type_t">mime_type_t
</a> *mimeType (
<br>
797 <a href=
"#mime_t">mime_t
</a> *mime,
<br>
798 <a href=
"#const">const
</a> char *super,
<br>
799 <a href=
"#const">const
</a> char *type
<br>
801 <h4 class=
"parameters">Parameters
</h4>
804 <dd class=
"description">MIME database
</dd>
806 <dd class=
"description">Super-type name
</dd>
808 <dd class=
"description">Type name
</dd>
810 <h4 class=
"returnvalue">Return Value
</h4>
811 <p class=
"description">Matching file type definition
</p>
812 <h2 class=
"title"><a name=
"TYPES">Data Types
</a></h2>
813 <h3 class=
"typedef"><a name=
"const">const
</a></h3>
814 <p class=
"description">MIME Database
</p>
816 typedef void (*constmime_error_cb_t)(void *;
818 <h3 class=
"typedef"><a name=
"mime_filter_t">mime_filter_t
</a></h3>
819 <p class=
"description">MIME Conversion Filter Data
</p>
821 typedef struct _mime_filter_s mime_filter_t;
823 <h3 class=
"typedef"><a name=
"mime_magic_t">mime_magic_t
</a></h3>
824 <p class=
"description">MIME Magic Data
</p>
826 typedef struct _mime_magic_s mime_magic_t;
828 <h3 class=
"typedef"><a name=
"mime_op_t">mime_op_t
</a></h3>
829 <p class=
"description">Types/structures...
</p>
831 typedef enum mime_op_t;
833 <h3 class=
"typedef"><a name=
"mime_t">mime_t
</a></h3>
834 <p class=
"description">MIME Database
</p>
836 typedef struct _mime_s mime_t;
838 <h3 class=
"typedef"><a name=
"mime_type_t">mime_type_t
</a></h3>
839 <p class=
"description">MIME Type Data
</p>
841 typedef struct _mime_type_s mime_type_t;