Update.
[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
489                                                    separator)
490   Decode MIME encoded-words in header fields.
491
492   If CODE-CONVERSION is nil, it decodes only encoded-words.  If it is
493   mime-charset, it decodes non-ASCII bit patterns as the mime-charset.
494   Otherwise it decodes non-ASCII bit patterns as the
495   default-mime-charset.
496
497   If SEPARATOR is not nil, it is used as header separator.
498
499   [Suggest]
500
501
502 [Function] [Function] eword-decode-header (&optional code-conversion
503                                                      separator)
504   As same as `mime-decode-header-in-buffer', q.v.
505
506   Note that
507
508        (require 'eword-decode)
509
510   is necessary to use this function.
511
512   [Optional]<Obsolete> (Usage: cmail 2.61)
513
514
515 [Function] mime-decode-header-in-region (start end
516                                          &optional code-conversion)
517   Decode MIME encoded-words in region between START and END.
518
519   If CODE-CONVERSION is nil, it decodes only encoded-words.  If it is
520   mime-charset, it decodes non-ASCII bit patterns as the mime-charset.
521   Otherwise it decodes non-ASCII bit patterns as the
522   default-mime-charset.
523
524   [Suggest]
525
526
527 [Function] mime-decode-field-body (field-body field-name
528                                    &optional mode max-column)
529   Decode FIELD-BODY as FIELD-NAME in MODE, and return the result.
530
531   Optional argument MODE must be `plain', `wide', `summary' or `nov'.
532   Default mode is `summary'.
533
534   If MODE is `wide' and MAX-COLUMN is non-nil, the result is folded
535   with MAX-COLUMN.
536
537   Non MIME encoded-word part in FILED-BODY is decoded with
538   `default-mime-charset'.
539
540   [Required]<Suggest>
541
542
543 [Function] mime-set-field-decoder (field &rest specs)
544   Set decoder of FIELD.
545
546   SPECS must be like `MODE1 DECODER1 MODE2 DECODER2 ...'.
547
548   Each mode must be `nil', `plain', `wide', `summary' or `nov'.  If
549   mode is `nil', corresponding decoder is set up for every modes.
550
551   [Suggest]
552
553
554 [Macro] mime-find-field-presentation-method (name)
555   Return field-presentation-method from NAME.
556
557   NAME must be `plain', `wide', `summary' or `nov'.
558
559   [Suggest]
560
561
562 [Function] mime-find-field-decoder (field &optional mode)
563   Return function to decode field-body of FIELD in MODE.
564
565   Optional argument MODE must be object or name of
566   field-presentation-method.  Name of field-presentation-method must
567   be `plain', `wide', `summary' or `nov'.  Default value of MODE is
568   `summary'.
569
570   [Suggest]
571
572
573 [Function] mime-update-field-decoder-cache (field mode &optional function)
574   Update field decoder cache `mime-field-decoder-cache'.
575
576   [Suggest]
577
578
579 ** encoder
580
581 [Function] mime-encode-header-in-buffer (&optional code-conversion)
582   Encode header fields to network representation, such as MIME
583   encoded-word.
584
585   It refer variable `mime-field-encoding-method-alist'.
586
587   [Suggest]
588
589
590 [Function] mime-encode-field-body (field-body field-name)
591   Encode FIELD-BODY as FIELD-NAME, and return the result.
592
593   A lexical token includes non-ASCII character is encoded as MIME
594   encoded-word.  ASCII token is not encoded.
595
596   [Required]<Suggest>
597
598
599 * Content-Transfer-Encoding
600
601 ** How to use
602
603 (require 'mel)
604
605
606 ** Encoding Name
607
608 [Variable] mime-encoding-list
609   List of Content-Transfer-Encoding.  Each encoding must be string.
610
611   [Suggest]
612
613
614 [Function] mime-encoding-list (&optional service)
615   Return list of Content-Transfer-Encoding.
616
617   If SERVICE is specified, it returns available list of
618   Content-Transfer-Encoding for it.
619
620   [Required]<Suggest>
621
622
623 [Function] mime-encoding-alist (&optional service)
624   Return table of Content-Transfer-Encoding for completion.
625
626   [Suggest]
627
628
629 ** Decoder
630
631 [Function] mime-decode-string (string encoding)
632   Decode STRING using ENCODING.
633
634   ENCODING must be string.  If ENCODING is found in
635   `mime-encoding-list', this function decodes the STRING by its value.
636
637   [Required]<Suggest>
638
639
640 [Function] mime-decode-region (start end encoding)
641   Decode region START to END of current buffer using ENCODING.
642
643   ENCODING must be string.
644
645   [Suggest]<Not Suggest>
646
647
648 [Function] mime-write-decoded-region (start end filename encoding)
649   Decode and write current region encoded by ENCODING into FILENAME.
650
651   START and END are buffer positions.
652
653   [Required]<Suggest>
654
655
656 ** Encoder
657
658 [Function] mime-encode-string (string encoding)
659   Encode STRING using ENCODING.
660
661   ENCODING must be string.
662
663   [Optional]<Not Suggest>
664
665
666 [Function] mime-encode-region (start end encoding)
667   Encode region START to END of current buffer using ENCODING.
668
669   ENCODING must be string.
670
671   [Suggest]<Not Suggest>
672
673
674 [Function] mime-insert-encoded-file (filename encoding)
675   Insert file FILENAME encoded by ENCODING format.
676
677   [Required]<Suggest>
678
679
680 ** encoded-text
681
682 [Function] encoded-text-decode-string (string encoding)
683   Decode STRING as encoded-text using ENCODING.
684
685   ENCODING must be string.
686
687   [Suggest]
688
689
690 [Function] encoded-text-encode-string (string encoding &optional mode)
691   Encode STRING as encoded-text using ENCODING.
692
693   ENCODING must be string.
694
695   MODE allows `text', `comment', `phrase' or nil.  Default value is
696   `phrase'.
697
698   [Suggest]
699
700
701 [Function] base64-encoded-length (string)
702   Return length of B-encoded STRING.
703
704   [Suggest]
705
706
707 [Function] Q-encoded-text-length (string &optional mode)
708   Return length of Q-encoded STRING.
709
710   MODE allows `text', `comment', `phrase' or nil.  Default value is
711   `phrase'.
712
713   [Suggest]
714
715
716 * Mailcap
717
718 ** How to use
719
720 (require 'mime-conf)
721
722
723 ** Parsing
724
725 [Function] mime-parse-mailcap-buffer (&optional buffer order)
726   Parse BUFFER as a mailcap, and return the result.
727
728   If optional argument ORDER is a function, result is sorted by it.
729   If optional argument ORDER is not specified, result is sorted
730   original order.  Otherwise result is not sorted.
731
732   [Required]<Suggest>
733
734
735 [Variable] mime-mailcap-file
736   File name of user's mailcap file.
737
738   [Required]<Suggest> (default value may be "~/.mailcap")
739
740
741 [Function] mime-parse-mailcap-file (&optional filename order)
742   Parse FILENAME as a mailcap, and return the result.
743
744   If optional argument ORDER is a function, result is sorted by it.
745   If optional argument ORDER is not specified, result is sorted
746   original order.  Otherwise result is not sorted.
747
748   [Required]<Suggest>
749
750
751 ** Apply
752
753 [Function] mime-format-mailcap-command (mtext situation)
754   Return formated command string from MTEXT and SITUATION.
755
756   MTEXT is a command text of mailcap specification, such as
757   view-command.
758
759   SITUATION is an association-list about information of entity.  Its
760   key may be:
761
762         'type           primary media-type
763         'subtype        media-subtype
764         'filename       filename
765         STRING          parameter of Content-Type field
766
767   [Required]<Suggest>
768
769
770 * MIME Field parsing
771
772 ** How to use
773
774 (require 'mime)
775
776
777 ** Level 2 features
778
779 [Variable] mime-field-parser-alist
780   Alist to specify field parser.
781
782
783 [Function] mime-parse-Content-Type (string)
784   Parse STRING as field-body of Content-Type field.
785
786 Return value is
787     (PRIMARY-TYPE SUBTYPE (NAME1 . VALUE1)(NAME2 . VALUE2) ...)
788 or nil.  PRIMARY-TYPE and SUBTYPE are symbol and NAME_n and VALUE_n
789 are string.
790
791
792 [Function] mime-read-Content-Type ()
793   Read field-body of Content-Type field from current-buffer,
794 and return parsed it.  Format of return value is as same as
795 `mime-parse-Content-Type'.
796
797
798 [Function] mime-parse-Content-Disposition (string)
799   Parse STRING as field-body of Content-Disposition field.
800
801
802 [Function] mime-read-Content-Disposition ()
803   Read field-body of Content-Disposition field from current-buffer,
804 and return parsed it.
805
806
807 [Function] mime-parse-Content-Transfer-Encoding (string)
808   Parse STRING as field-body of Content-Transfer-Encoding field.
809
810
811 [Function] mime-read-Content-Transfer-Encoding (&optional default-encoding)
812   Read field-body of Content-Transfer-Encoding field from
813 current-buffer, and return it.
814
815 If is is not found, return DEFAULT-ENCODING.
816
817
818 [Function] mime-parse-msg-id (tokens)
819   Parse TOKENS as msg-id of Content-Id or Message-Id field.
820
821
822 [Function] mime-uri-parse-cid (string)
823   Parse STRING as cid URI.
824
825
826 * STD 11 parsing
827
828 ** How to use
829
830 (require 'std11)
831
832
833 ** Level 1 features
834
835 [Function] std11-fetch-field (name)
836   Return the value of the header field NAME.
837
838 The buffer is expected to be narrowed to just the headers of the message.
839
840
841 [Function] std11-narrow-to-header (&optional boundary)
842   Narrow to the message header.
843
844 If BOUNDARY is not nil, it is used as message header separator.
845
846
847 [Function] std11-field-body (name &optional boundary)
848   Return the value of the header field NAME.
849
850 If BOUNDARY is not nil, it is used as message header separator.
851
852
853 [Function] std11-unfold-string (string)
854   Unfold STRING as message header field.
855
856
857 ** Level 2 features
858
859 [Function] std11-lexical-analyze (string &optional analyzer start)
860   Analyze STRING as lexical tokens of STD 11.
861
862
863 [Function] std11-address-string (address)
864   Return string of address part from parsed ADDRESS of RFC 822.
865
866
867 [Function] std11-full-name-string (address)
868   Return string of full-name part from parsed ADDRESS of RFC 822.
869
870
871 [Function] std11-msg-id-string (msg-id)
872   Return string from parsed MSG-ID of RFC 822.
873
874
875 [Function] std11-fill-msg-id-list-string (string &optional column)
876   Fill list of msg-id in STRING, and return the result.
877
878
879 [Function] std11-parse-address-string (string)
880   Parse STRING as mail address.
881
882
883 [Function] std11-parse-addresses-string (string)
884   Parse STRING as mail address list.
885
886
887 [Function] std11-parse-msg-id-string (string)
888   Parse STRING as msg-id.
889
890
891 [Function] std11-parse-msg-ids-string (string)
892   Parse STRING as `*(phrase / msg-id)'.
893
894
895 [Function] std11-extract-address-components (string)
896   Extract full name and canonical address from STRING.
897
898   Returns a list of the form (FULL-NAME CANONICAL-ADDRESS).  If no
899   name can be extracted, FULL-NAME will be nil.
900
901
902 * SMTP
903
904 ** How to use
905
906 (require 'smtp)
907
908
909 ** Features
910
911 [Function] smtp-send-buffer (sender recipients buffer)
912   Send a message.
913
914   SENDER is an envelope sender address.
915   RECIPIENTS is a list of envelope recipient addresses.
916   BUFFER may be a buffer or a buffer name which contains mail message.
917
918   [Suggest]
919
920 [Function] smtp-via-smtp (sender recipients buffer)
921   Like `smtp-send-buffer', but sucks in any errors.
922
923   [Optional]<Not Suggest>