Add some usages.
[elisp/flim.git] / FLIM-API.en
1           FLIM (Faithful Library about Internet Message) API
2                              Version 1.14
3                            Draft Release 1
4
5 * Notation
6
7 Each function is described by following notation:
8
9 [Function] NAME-OF-FUNCTION (SIGNATURE)
10   DESCRIPTIONS
11   [ILEVEL]<ULEVEL>
12
13 Each inline function is described by following notation:
14
15 [Inline function] NAME-OF-FUNCTION (SIGNATURE)
16   DESCRIPTIONS
17   [ILEVEL]<ULEVEL>
18
19 Each macro is described by following notation:
20
21 [Macro] NAME-OF-MACRO (SIGNATURE)
22   DESCRIPTIONS
23   [ILEVEL]<ULEVEL>
24
25 Each variable is described by following notation:
26
27 [Variable] NAME-OF-VARIABLE
28   DESCRIPTIONS
29   [ILEVEL]<ULEVEL>
30
31 ILEVEL specifies implementation level:
32
33   Required: Must implement
34   Suggest:  Should implement
35   Optional: Optional
36
37 ULEVEL specifies implementation level:
38
39   Suggest:  Should use
40   Not Suggest: Should not use
41   Obsolete: Should not use (historical)
42
43
44 * MIME entity
45
46 ** How to use
47
48 (require 'mime)
49
50
51 ** MIME-Entity Creation
52
53 [Function] mime-open-entity (type location)
54   Open an entity and return it.
55
56   TYPE is representation-type.
57
58   LOCATION is location of entity.  Specification of it is depended on
59   representation-type.
60
61   [Required]<Suggest>
62   (Usage: SEMI 1.14 MIME-View)
63
64
65 [Function] mime-parse-buffer (&optional buffer representation-type)
66   Parse BUFFER as a MIME message.
67
68   If buffer is omitted, it parses current-buffer.
69
70   [Optional]<Not Suggest>
71
72
73 ** MIME-Entity Hierarchy
74
75 [Function] mime-entity-children (entity)
76   Return list of entities included in the ENTITY.
77
78   [Required]<Suggest>
79   (Usage: SEMI 1.14 MIME-View, MIME-PGP)
80
81
82 [Function] mime-entity-parent (entity &optional message)
83   Return mother entity of ENTITY.
84
85   If MESSAGE is specified, it is regarded as root entity.
86
87   [Suggest]
88   (Usage: SEMI 1.14 MIME-View, MIME-PGP)
89
90
91 [Function] mime-find-root-entity (entity)
92   Return root entity of ENTITY.
93
94   [Suggest]
95
96
97 [Function] mime-root-entity-p (entity &optional message)
98   Return t if ENTITY is root-entity (message).
99
100   If MESSAGE is specified, it is regarded as root entity.
101
102   [Suggest]<Suggest>
103
104
105 [Function] mime-entity-node-id (entity)
106   Return node-id of ENTITY.
107
108   [Suggest]
109   (Usage: SEMI 1.14 MIME-View, MIME-PGP)
110
111
112 [Function] mime-entity-number (entity)
113   Return entity-number of ENTITY.
114
115   [Optional]
116   (Usage: SEMI 1.14 MIME-View, MIME-PGP)
117
118
119 ** MIME-Entity Search
120
121 [Function] mime-find-entity-from-node-id (entity-node-id message)
122   Return entity from ENTITY-NODE-ID in MESSAGE.
123
124   [Suggest]
125
126
127 [Function] mime-find-entity-from-number (entity-number message)
128   Return entity from ENTITY-NUMBER in MESSAGE.
129
130   [Optional]
131
132
133 [Function] mime-find-entity-from-content-id (cid message)
134   Return entity from CID in MESSAGE.
135
136   [Suggest]<Suggest>
137
138
139 ** MIME-Entity Attributes
140
141 [Function] mime-entity-content-type (entity)
142   Return content-type of ENTITY.
143
144   (cf. <** Content-Type>)
145
146   [Suggest]
147   (Usage: SEMI 1.14 MIME-View)
148
149
150 [Inline function] mime-entity-media-type (entity)
151   Return primary media-type of ENTITY.
152
153   [Suggest]<Not Suggest>
154   (Usage: SEMI 1.14 MIME-View)
155
156
157 [Inline function] mime-entity-media-subtype (entity)
158   Return media-subtype of ENTITY.
159
160   [Suggest]<Not Suggest>
161   (Usage: SEMI 1.14 MIME-View)
162
163
164 [Inline function] mime-entity-type/subtype (entity)
165   Return media-type/subtype of ENTITY.
166
167   [Suggest]
168   (Usage: SEMI 1.14 MIME-W3)
169
170
171 [Inline function] mime-entity-parameters (entity)
172   Return parameters of Content-Type of ENTITY.
173
174   [Suggest]<Not Suggest>
175   (Usage: SEMI 1.14 MIME-View)
176
177
178 [Function] mime-entity-set-content-type (entity content-type)
179   Set ENTITY's content-type to CONTENT-TYPE.
180
181   (cf. <** Content-Type>)
182
183   [Suggest]
184   (Usage: SEMI 1.14 MIME-View)
185
186
187 [Function] mime-entity-content-disposition (entity)
188   Return content-disposition of ENTITY.
189
190   (cf. <** Content-Disposition>)
191
192   [Suggest]
193   (Usage: SEMI 1.14 MIME-View)
194
195
196 [Function] mime-entity-filename (entity)
197   Return filename of ENTITY.
198
199   [Suggest]
200   (Usage: SEMI 1.14 MIME-View)
201
202
203 [Function] mime-entity-encoding (entity &optional default-encoding)
204   Return content-transfer-encoding of ENTITY.
205
206   If the ENTITY does not have Content-Transfer-Encoding field, this
207   function returns DEFAULT-ENCODING.  If it is nil, "7bit" is used as
208   default value.
209
210   [Suggest]
211   (Usage: SEMI 1.14 MIME-View)
212
213
214 [Function] mime-entity-set-encoding (entity encoding)
215   Set ENTITY's content-transfer-encoding to ENCODING.
216
217   [Suggest]
218   (Usage: SEMI 1.14 MIME-View)
219
220
221 [Function] mime-entity-cooked-p (entity)
222   Return non-nil if contents of ENTITY has been already
223   code-converted.
224
225   [Suggest]
226   (Usage: SEMI 1.14 MIME-PGP)
227
228
229 [Function] mime-entity-name (entity)
230   Return unique name of the ENTITY.
231
232   [Suggest]
233   (Usage: SEMI 1.14 MIME-View)
234
235
236 ** MIME-Entity Header
237
238 [Function] mime-entity-fetch-field (entity field-name)
239   Return the value of the ENTITY's header field whose type is
240   FIELD-NAME.
241
242   The results is network representation.
243
244   If FIELD-NAME field is not found, this function returns nil.
245
246   [Required]<Suggest>
247   (Usage: SEMI 1.14 MIME-View, MIME-BBDB)
248
249
250 [Function] mime-entity-read-field (entity field-name)
251   Parse FIELD-NAME field in header of ENTITY, and return the result.
252
253   Format of result is depended on kind of field.  For non-structured
254   field, this function returns string.  For structured field, it
255   returns list corresponding with structure of the field.
256
257   Strings in the result will be converted to internal representation
258   of Emacs.
259
260   If FIELD-NAME field is not found, this function returns nil.
261
262   [Suggest]
263   (Usage: SEMI 1.14 MIME-View, MIME-BBDB)
264
265
266 ** Text Presentation of MIME-Entity Content
267
268 [Function] mime-insert-header (entity &optional invisible-fields
269                                                 visible-fields)
270   Insert before point a decoded header of ENTITY.
271
272   INVISIBLE-FIELDS is list of regexps to match field-name to hide.
273   VISIBLE-FIELDS is list of regexps to match field-name to hide.
274
275   If a field-name is matched with some elements of INVISIBLE-FIELDS
276   and matched with none of VISIBLE-FIELDS, this function don't insert
277   the field.
278
279   Each encoded-word in the header is decoded.  ``Raw non us-ascii
280   characters'' are also decoded as `default-mime-charset'.
281
282   [Suggest]
283
284
285 [Function] mime-insert-text-content (entity)
286   Insert before point a contents of ENTITY as text entity.
287
288   Contents of the ENTITY are decoded as MIME charset.  If the ENTITY
289   does not have charset parameter of Content-Type field,
290   `default-mime-charset' is used as default value.
291
292   [Required]
293
294
295 [Variable] default-mime-charset
296   Symbol to indicate default value of MIME charset.
297
298   It is used when MIME charset is not specified.
299
300   It is originally variable of APEL.
301
302   [Required]
303
304
305 ** Bytes Representation of MIME-Entity Content
306
307 [Function] mime-entity-content (entity)
308   Return content of ENTITY as byte sequence (string).
309
310   [Required]
311   (Usage: SEMI 1.14 MIME-View, Postpet)
312
313
314 [Function] mime-insert-entity-content (entity)
315   Insert content of ENTITY (byte sequence) at point.
316
317   [Suggest]
318
319
320 [Function] mime-write-entity-content (entity filename)
321   Write content of ENTITY (byte sequence) into FILENAME.
322
323   [Required]
324
325
326 ** Network Representation of MIME-Entity
327
328 [Function] mime-entity-string (entity)
329   Return header and body of ENTITY (string).
330
331   [Optional]<Not Suggest>
332
333
334 [Function] mime-insert-entity (entity)
335   Insert header and body of ENTITY at point.
336
337   [Required]
338
339
340 [Function] mime-write-entity (entity filename)
341   Write header and body of ENTITY into FILENAME.
342
343   [Required]
344
345
346 [Function] mime-entity-header (entity)
347   Return network representation of ENTITY header (string).
348
349   [Optional]<Not Suggest>
350
351
352 [Function] mime-insert-entity-header (entity)
353   Insert network representation of ENTITY header at point.
354
355   [Optional]<Not Suggest>
356
357
358 [Function] mime-write-entity-header (entity filename)
359   Write network representation of ENTITY header FILENAME.
360
361   [Optional]<Not Suggest>
362
363
364 [Function] mime-entity-body (entity)
365   Return network representation of ENTITY body (string).
366
367   [Optional]<Not Suggest>
368
369
370 [Function] mime-insert-entity-body (entity)
371   Insert network representation of ENTITY body at point.
372
373   [Required]
374
375
376 [Function] mime-write-entity-body (entity filename)
377   Write body of ENTITY into FILENAME.
378
379   [Required]
380
381
382 * MIME content information
383
384 ** How to use
385
386 (require 'mime)
387
388
389 ** Content-Type
390
391 [Function] mime-parse-Content-Type (string)
392   Parse STRING as field-body of Content-Type field, and
393   return the result as `mime-content-type' structure.
394
395   [Suggest]
396
397
398 [Function] mime-read-Content-Type ()
399   Read field-body of Content-Type field from current-buffer,
400   and return the parsed result.
401
402   Format of return value is as same as `mime-parse-Content-Type'.
403
404   Return `nil' if Content-Type field is not found.
405
406   [Suggest]
407
408
409 [Inline function] mime-content-type-primary-type (content-type)
410   Return primary-type of CONTENT-TYPE.
411
412   [Required]
413
414
415 [Inline function] mime-content-type-subtype (content-type)
416   Return subtype of CONTENT-TYPE.
417
418   [Required]
419
420
421 [Inline function] mime-content-type-parameter (content-type parameter)
422   Return PARAMETER value of CONTENT-TYPE.
423
424   [Required]
425
426
427 [Inline function] mime-content-type-parameters (content-type)
428   Return parameters of CONTENT-TYPE.
429
430   [Suggest]
431
432
433 [Inline function] mime-type/subtype-string (type &optional subtype)
434   Return type/subtype string from TYPE and SUBTYPE.
435
436   [Suggest]
437
438
439 ** Content-Disposition
440
441 [Function] mime-parse-Content-Disposition (string)
442   Parse STRING as field-body of Content-Disposition field.
443
444   [Suggest]
445
446
447 [Function] mime-read-Content-Disposition ()
448   Read field-body of Content-Disposition field from current-buffer,
449 and return parsed it.
450
451   [Suggest]
452
453
454 [Inline function] mime-content-disposition-type (content-disposition)
455   Return disposition-type of CONTENT-DISPOSITION.
456
457   [Required]
458
459
460 [Inline function] mime-content-disposition-parameter
461                                 (content-disposition parameter)
462   Return PARAMETER value of CONTENT-DISPOSITION.
463
464   [Required]
465
466
467 [Inline function] mime-content-disposition-filename (content-disposition)
468   Return filename of CONTENT-DISPOSITION.
469
470   [Suggest]<Suggest>
471
472
473 [Inline function] mime-content-disposition-parameters (content-disposition)
474   Return disposition-parameters of CONTENT-DISPOSITION.
475
476   [Suggest]
477
478
479 * encoded-word
480
481 ** How to use
482
483 (require 'mime)
484
485
486 ** decoder
487
488 [Function] mime-decode-header-in-buffer (&optional code-conversion separator)
489   Decode MIME encoded-words in header fields.
490
491   If CODE-CONVERSION is nil, it decodes only encoded-words.  If it is
492   mime-charset, it decodes non-ASCII bit patterns as the mime-charset.
493   Otherwise it decodes non-ASCII bit patterns as the
494   default-mime-charset.
495
496   If SEPARATOR is not nil, it is used as header separator.
497
498   [Suggest]
499
500
501 [Function] mime-decode-header-in-region (start end
502                                          &optional code-conversion)
503   Decode MIME encoded-words in region between START and END.
504
505   If CODE-CONVERSION is nil, it decodes only encoded-words.  If it is
506   mime-charset, it decodes non-ASCII bit patterns as the mime-charset.
507   Otherwise it decodes non-ASCII bit patterns as the
508   default-mime-charset.
509
510   [Suggest]
511
512
513 [Function] mime-decode-field-body (field-body field-name
514                                    &optional mode max-column)
515   Decode FIELD-BODY as FIELD-NAME in MODE, and return the result.
516
517   Optional argument MODE must be `plain', `wide', `summary' or `nov'.
518   Default mode is `summary'.
519
520   If MODE is `wide' and MAX-COLUMN is non-nil, the result is folded
521   with MAX-COLUMN.
522
523   Non MIME encoded-word part in FILED-BODY is decoded with
524   `default-mime-charset'.
525
526   [Required]<Suggest>
527
528
529 [Function] mime-set-field-decoder (field &rest specs)
530   Set decoder of FIELD.
531
532   SPECS must be like `MODE1 DECODER1 MODE2 DECODER2 ...'.
533
534   Each mode must be `nil', `plain', `wide', `summary' or `nov'.  If
535   mode is `nil', corresponding decoder is set up for every modes.
536
537   [Suggest]
538
539
540 [Macro] mime-find-field-presentation-method (name)
541   Return field-presentation-method from NAME.
542
543   NAME must be `plain', `wide', `summary' or `nov'.
544
545   [Suggest]
546
547
548 [Function] mime-find-field-decoder (field &optional mode)
549   Return function to decode field-body of FIELD in MODE.
550
551   Optional argument MODE must be object or name of
552   field-presentation-method.  Name of field-presentation-method must
553   be `plain', `wide', `summary' or `nov'.  Default value of MODE is
554   `summary'.
555
556   [Suggest]
557
558
559 [Function] mime-update-field-decoder-cache (field mode &optional function)
560   Update field decoder cache `mime-field-decoder-cache'.
561
562   [Suggest]
563
564
565 ** encoder
566
567 [Function] mime-encode-header-in-buffer (&optional code-conversion)
568   Encode header fields to network representation, such as MIME
569   encoded-word.
570
571   It refer variable `mime-field-encoding-method-alist'.
572
573   [Suggest]
574
575
576 [Function] mime-encode-field-body (field-body field-name)
577   Encode FIELD-BODY as FIELD-NAME, and return the result.
578
579   A lexical token includes non-ASCII character is encoded as MIME
580   encoded-word.  ASCII token is not encoded.
581
582   [Required]<Suggest>
583
584
585 * Content-Transfer-Encoding
586
587 ** How to use
588
589 (require 'mel)
590
591
592 ** Encoding Name
593
594 [Variable] mime-encoding-list
595   List of Content-Transfer-Encoding.  Each encoding must be string.
596
597   [Suggest]
598
599
600 [Function] mime-encoding-list (&optional service)
601   Return list of Content-Transfer-Encoding.
602
603   If SERVICE is specified, it returns available list of
604   Content-Transfer-Encoding for it.
605
606   [Required]<Suggest>
607
608
609 [Function] mime-encoding-alist (&optional service)
610   Return table of Content-Transfer-Encoding for completion.
611
612   [Suggest]
613
614
615 ** Decoder
616
617 [Function] mime-decode-string (string encoding)
618   Decode STRING using ENCODING.
619
620   ENCODING must be string.  If ENCODING is found in
621   `mime-encoding-list', this function decodes the STRING by its value.
622
623   [Required]<Suggest>
624
625
626 [Function] mime-decode-region (start end encoding)
627   Decode region START to END of current buffer using ENCODING.
628
629   ENCODING must be string.
630
631   [Suggest]<Not Suggest>
632
633
634 [Function] mime-write-decoded-region (start end filename encoding)
635   Decode and write current region encoded by ENCODING into FILENAME.
636
637   START and END are buffer positions.
638
639   [Required]<Suggest>
640
641
642 ** Encoder
643
644 [Function] mime-encode-string (string encoding)
645   Encode STRING using ENCODING.
646
647   ENCODING must be string.
648
649   [Optional]<Not Suggest>
650
651
652 [Function] mime-encode-region (start end encoding)
653   Encode region START to END of current buffer using ENCODING.
654
655   ENCODING must be string.
656
657   [Suggest]<Not Suggest>
658
659
660 [Function] mime-insert-encoded-file (filename encoding)
661   Insert file FILENAME encoded by ENCODING format.
662
663   [Required]<Suggest>
664
665
666 ** encoded-text
667
668 [Function] encoded-text-decode-string (string encoding)
669   Decode STRING as encoded-text using ENCODING.
670
671   ENCODING must be string.
672
673   [Suggest]
674
675
676 [Function] encoded-text-encode-string (string encoding &optional mode)
677   Encode STRING as encoded-text using ENCODING.
678
679   ENCODING must be string.
680
681   MODE allows `text', `comment', `phrase' or nil.  Default value is
682   `phrase'.
683
684   [Suggest]
685
686
687 [Function] base64-encoded-length (string)
688   Return length of B-encoded STRING.
689
690   [Suggest]
691
692
693 [Function] Q-encoded-text-length (string &optional mode)
694   Return length of Q-encoded STRING.
695
696   MODE allows `text', `comment', `phrase' or nil.  Default value is
697   `phrase'.
698
699   [Suggest]
700
701
702 * Mailcap
703
704 ** How to use
705
706 (require 'mime-conf)
707
708
709 ** Parsing
710
711 [Function] mime-parse-mailcap-buffer (&optional buffer order)
712   Parse BUFFER as a mailcap, and return the result.
713
714   If optional argument ORDER is a function, result is sorted by it.
715   If optional argument ORDER is not specified, result is sorted
716   original order.  Otherwise result is not sorted.
717
718   [Required]<Suggest>
719
720
721 [Variable] mime-mailcap-file
722   File name of user's mailcap file.
723
724   [Required]<Suggest> (default value may be "~/.mailcap")
725
726
727 [Function] mime-parse-mailcap-file (&optional filename order)
728   Parse FILENAME as a mailcap, and return the result.
729
730   If optional argument ORDER is a function, result is sorted by it.
731   If optional argument ORDER is not specified, result is sorted
732   original order.  Otherwise result is not sorted.
733
734   [Required]<Suggest>
735
736
737 ** Apply
738
739 [Function] mime-format-mailcap-command (mtext situation)
740   Return formated command string from MTEXT and SITUATION.
741
742   MTEXT is a command text of mailcap specification, such as
743   view-command.
744
745   SITUATION is an association-list about information of entity.  Its
746   key may be:
747
748         'type           primary media-type
749         'subtype        media-subtype
750         'filename       filename
751         STRING          parameter of Content-Type field
752
753   [Required]<Suggest>
754
755
756 * MIME Field parsing
757
758 ** How to use
759
760 (require 'mime)
761
762
763 ** Level 2 features
764
765 [Variable] mime-field-parser-alist
766   Alist to specify field parser.
767
768
769 [Function] mime-parse-Content-Type (string)
770   Parse STRING as field-body of Content-Type field.
771
772 Return value is
773     (PRIMARY-TYPE SUBTYPE (NAME1 . VALUE1)(NAME2 . VALUE2) ...)
774 or nil.  PRIMARY-TYPE and SUBTYPE are symbol and NAME_n and VALUE_n
775 are string.
776
777
778 [Function] mime-read-Content-Type ()
779   Read field-body of Content-Type field from current-buffer,
780 and return parsed it.  Format of return value is as same as
781 `mime-parse-Content-Type'.
782
783
784 [Function] mime-parse-Content-Disposition (string)
785   Parse STRING as field-body of Content-Disposition field.
786
787
788 [Function] mime-read-Content-Disposition ()
789   Read field-body of Content-Disposition field from current-buffer,
790 and return parsed it.
791
792
793 [Function] mime-parse-Content-Transfer-Encoding (string)
794   Parse STRING as field-body of Content-Transfer-Encoding field.
795
796
797 [Function] mime-read-Content-Transfer-Encoding (&optional default-encoding)
798   Read field-body of Content-Transfer-Encoding field from
799 current-buffer, and return it.
800
801 If is is not found, return DEFAULT-ENCODING.
802
803
804 [Function] mime-parse-msg-id (tokens)
805   Parse TOKENS as msg-id of Content-Id or Message-Id field.
806
807
808 [Function] mime-uri-parse-cid (string)
809   Parse STRING as cid URI.
810
811
812 * STD 11 parsing
813
814 ** How to use
815
816 (require 'std11)
817
818
819 ** Level 1 features
820
821 [Function] std11-fetch-field (name)
822   Return the value of the header field NAME.
823
824 The buffer is expected to be narrowed to just the headers of the message.
825
826
827 [Function] std11-narrow-to-header (&optional boundary)
828   Narrow to the message header.
829
830 If BOUNDARY is not nil, it is used as message header separator.
831
832
833 [Function] std11-field-body (name &optional boundary)
834   Return the value of the header field NAME.
835
836 If BOUNDARY is not nil, it is used as message header separator.
837
838
839 [Function] std11-unfold-string (string)
840   Unfold STRING as message header field.
841
842
843 ** Level 2 features
844
845 [Function] std11-lexical-analyze (string &optional analyzer start)
846   Analyze STRING as lexical tokens of STD 11.
847
848
849 [Function] std11-address-string (address)
850   Return string of address part from parsed ADDRESS of RFC 822.
851
852
853 [Function] std11-full-name-string (address)
854   Return string of full-name part from parsed ADDRESS of RFC 822.
855
856
857 [Function] std11-msg-id-string (msg-id)
858   Return string from parsed MSG-ID of RFC 822.
859
860
861 [Function] std11-fill-msg-id-list-string (string &optional column)
862   Fill list of msg-id in STRING, and return the result.
863
864
865 [Function] std11-parse-address-string (string)
866   Parse STRING as mail address.
867
868
869 [Function] std11-parse-addresses-string (string)
870   Parse STRING as mail address list.
871
872
873 [Function] std11-parse-msg-id-string (string)
874   Parse STRING as msg-id.
875
876
877 [Function] std11-parse-msg-ids-string (string)
878   Parse STRING as `*(phrase / msg-id)'.
879
880
881 [Function] std11-extract-address-components (string)
882   Extract full name and canonical address from STRING.
883
884   Returns a list of the form (FULL-NAME CANONICAL-ADDRESS).  If no
885   name can be extracted, FULL-NAME will be nil.
886
887
888 * SMTP
889
890 ** How to use
891
892 (require 'smtp)
893
894
895 ** Features
896
897 [Function] smtp-send-buffer (sender recipients buffer)
898   (This description will be written by Daiki Ueno <ueno@unixuser.org>)
899
900
901 * QMTP
902
903 ** How to use
904
905 (require 'qmtp)
906
907
908 ** Features
909
910 [Function] qmtp-send-buffer (sender recipients buffer)
911   (This description will be written by Daiki Ueno <ueno@unixuser.org>)