camel/README

   1
   2                                    CAMEL
   3
   4
   5                         A generic Messaging Library
   6
   7
   8                                    ----
   9
  10
  11 Introduction:
  12 -------------
  13
  14 Camel is a generic messaging library. It supports the standard
  15 messaging system for receiving and sending messages. It is the
  16 messaging backend for Evolution.
  17
  18 The name "camel" stands for ... nothing. Open area of development there.
  19 You know, that "bazaar" thing. Maybe could we organize a big contest on
  20 gnome-list to find the best explanation :)
  21
  22 Camel draws heavily from JavaMail and the IMAP4rev1 RFC. People
  23 wanting to hack on a provider should read the JavaMail API
  24 specification, but CMC and MAPI are of interest too.
  25
  26
  27 Organization:
  28 -------------
  29
  30 The library is roughly a set of abstract classes, some kind of generic
  31 "interfaces" (IDL interfaces, not Java interfaces).
  32
  33 Particular implementations are called providers.
  34
  35 Here are the basic objects:
  36
  37 * CamelService : An abstract class representing an access to a server.
  38 Handles the connection and authentication to any server.
  39
  40 * CamelStore (CamelService): A hierarchy of folders on a server.
  41
  42 * CamelFolder : An object containing messages. A folder is always
  43 associated with a store.
  44
  45 * CamelMessage : An object contained in folders. Is defined by a set
  46 of attributes and a content. (Attributes include: the date it was
  47 received, the sender address, .....)
  48
  49 * CamelTransport (CamelService): A way to send messages.
  50
  51 ....
  52 ...
  53
  54
  55 #include Ordering:
  56 ------------------
  57
  58 Not all Unix system header files #include the headers that they
  59 themselves reference, so in order to maintain portability it is often
  60 important to #include headers in the proper order.
  61
  62 This information can often be deduced from reading the man pages
  63 involving the functions you are using.
  64
  65 For example, `man 2 open` informs us that the following headers are
  66 necessary and lists them in the following order:
  67
  68
  69 #include <sys/types.h>
  70 #include <sys/stat.h>
  71 #include <fcntl.h>
  72
  73
  74 Another common header that is often needed for low-level I/O is
  75 unistd.h which is required by functions such as read() and
  76 write(). The Linux man pages don't seem to specify what its
  77 dependencies are, but often it depends on sys/types.h.
  78
  79 If you are going to be doing any socket I/O you'll be needing
  80 sys/socket.h which often depends on sys/types.h.
  81
  82 A tried and true #include ordering scheme for source files doing I/O
  83 is this:
  84
  85
  86 #include <stdio.h>
  87 #include <stdlib.h>
  88 #include <string.h>
  89 #include <sys/types.h>
  90 #include <sys/socket.h>
  91 #include <sys/time.h>
  92 #include <sys/stat.h>
  93 #include <dirent.h>
  94 #include <unistd.h>
  95 #include <fcntl.h>
  96 #include <errno.h>
  97
  98 Feel free to cut out any headers your code doesn't actually need in
  99 the list.