home *** CD-ROM | disk | FTP | other *** search
/ PC World 2004 October / PCWorld_2004-10_cd.bin / software / vyzkuste / spyware / spyware.exe / akme32.exe / OleAutomation / OleDoc.txt < prev   
Encoding:
Text File  |  2002-11-27  |  14.2 KB  |  457 lines
  1.                       OLE Automation in AK-Mail
  2.                       -------------------------
  3.  
  4. 1. Overview
  5.  
  6.    With the new release of AK-Mail, AK-Mail can be controlled by OLE
  7.    automation. That means that a subset of the AK-Mail functionality
  8.    is available to external software. This feature is only available
  9.    in the registered version.
  10.    Please make sure that you are familiar with the OLE automation
  11.    technology. This reference cannot and will not explain any
  12.    OLE automation terms.
  13.  
  14.    The functions AK-Mail offers are divided into 3 groups as follows:
  15.  
  16.    1.) Functions to create a new outgoing mail
  17.  
  18.        Functions in this group allow you to place a new outgoing mail
  19.        in the outbox of any account. This is especially useful for sending
  20.        customized mail that goes to many people. Applications include
  21.        sending of on demand data or registration keys for software.
  22.        The functions can also be used to send highly customized mass mails.
  23.  
  24.    2.) Functions to examine folders
  25.        Functions to move/copy/delete messages
  26.  
  27.        Gives your own programs reading access to any folder. You can get a
  28.        list of messages in a folder and you can retrieve header and body
  29.        information of messages. There is no access to attachments.
  30.        There is no access to outgoing messages.
  31.        The functions are useful if you wish to automatically respond
  32.        to incoming mail in a way too specific for AK-Mail filters.
  33.        Because logic is in your external program there is nearly no
  34.        limit on how to use the information that the incoming messages
  35.        provide.
  36.  
  37.    3.) Functions to examine entries in address books
  38.        Functions to create/delete entries
  39.  
  40.        Gives you access to entries in address books.
  41.        Lets you create new address book entries in any address book.
  42.  
  43.  
  44. 2. Basic Operation
  45.  
  46.    The object name of AK-Mail is 'akmail.application' (without ').
  47.    If an object of this type already exists, you have to use that
  48.    object. Please check in your application. Creation of another
  49.    object will fail.
  50.  
  51.    The type library is stored in the akmail.exe file.
  52.  
  53.    Whenever a method returns a value it is an error code.
  54.    A value of zero means success, any other value means that
  55.    the method failed. For a list of error codes see Appendix A.
  56.  
  57.    Please note: The interface described in this file is subject to
  58.                 change without notice.
  59.  
  60.    OLE automation with AK-Mail is easy to use. Have fun!
  61.  
  62.  
  63. 3. Reference
  64.  
  65.    This reference part documents all methods and properties available
  66.    in AK-Mail. Syntax used is pseudo C++ / pseudo VB style.
  67.  
  68.    1. Group: Functions to create a new outgoing mail
  69.  
  70.      Methods:
  71.  
  72.        long StoreNewMail(BSTR account)
  73.  
  74.          Parameters:
  75.  
  76.            account = String that contains an account name. The new mail
  77.                      will be stored in the outbox of that account.
  78.  
  79.          What it does:
  80.  
  81.            StoreNewMail creates a new mail in the outbox of the
  82.            given account. The following properties are used to
  83.            generate the mail:
  84.  
  85.              ToField, CcField, BccField, Subject, Body
  86.  
  87.            Load the properties shown above with the values you
  88.            wish to use for the new mail. Then call StoreNewMail.
  89.  
  90.  
  91.        long StoreNewMailOptions(BSTR account,long options)
  92.  
  93.          Parameters:
  94.  
  95.            account = String that contains an account name. The new mail
  96.                      will be stored in the outbox of that account.
  97.  
  98.            options = Bitfield value, specifies additional options
  99.  
  100.                        Bit     0 ..... Set stop mark
  101.                        Bit     1 ..... Encrypt using PGP
  102.                        Bit     2 ..... Sign using PGP
  103.                        Bit     3 ..... Return receipt
  104.                        Bit  4-31 ..... currently not used
  105.  
  106.          What it does:
  107.  
  108.            StoreNewMailOptions is the same as StoreNewMail with
  109.            the additional options parameter.
  110.  
  111.  
  112.        long StoreNewMailAtt(BSTR account,BSTR attachment)
  113.        long StoreNewMailAttOptions(BSTR account,BSTR attachment,long options)
  114.  
  115.          Parameters:
  116.  
  117.            account    = String that contains an account name. The new mail
  118.                         will be stored in the outbox of that account.
  119.  
  120.            attachment = One or more attachments to attach to the new mail.
  121.                         Specify the full filename (for example
  122.                         "c:\dir1\dir2\file.ext"). Separate multiple attachments
  123.                         through semicolons (for example "c:\file1;c:\file2").
  124.  
  125.            options    = Bitfield value, specifies additional options.
  126.                         See above for details.
  127.  
  128.          What it does:
  129.  
  130.            StoreNewMailAtt and StoreNewMailAttOptions are extensions of
  131.            StoreNewMail and StoreNewMailOptions. They allow you to attach files to
  132.            the new mail.
  133.  
  134.  
  135.      Properties:
  136.  
  137.        BSTR ToField
  138.  
  139.          Stores the string that is to be placed in the To: field
  140.          of a new outgoing mail. Separate multiple recipients by
  141.          a comma or a new line character. Alias names are allowed.
  142.          In general everything that is allowed in the composer
  143.          window of AK-Mail is allowed here too.
  144.  
  145.        BSTR CcField
  146.  
  147.          Same as ToField but for Cc: field.
  148.  
  149.        BSTR BccField
  150.  
  151.          Same as ToField but for Bcc: field.
  152.  
  153.        BSTR Subject
  154.  
  155.          Stores the subject that is to be placed in the Subject:
  156.          field of a new outgoing mail. This property is used by
  157.          group 2 functions also.
  158.  
  159.        BSTR Body
  160.  
  161.          Stores the body that is to be used for the creation of
  162.          the new mail. To use multiple lines of text you can
  163.          use the new line character. The following two character
  164.          sequences are recognized as new line indicator:
  165.  
  166.            a) 0x0A
  167.            b) 0x0D 0x0A
  168.  
  169.          This property is used by group 2 functions also.
  170.  
  171.      Example:
  172.  
  173.        akmobj.ToField="testuser@testdomain.com"
  174.        akmobj.CcField=""
  175.        akmobj.BccField=""
  176.        akmobj.Subject="Just a test"
  177.        akmobj.Body="This is the body of the mail"
  178.        akmobj.StoreNewMail "MyAccount"
  179.  
  180.  
  181.    2. Group: Functions to examine folders
  182.  
  183.      Methods:
  184.  
  185.        long ScanFolder(BSTR folderpath)
  186.  
  187.          Parameters:
  188.  
  189.            folderpath = String that contains a full path to a folder.
  190.                         A full path starts with an account name
  191.                         or '/' for the special folder. Examples are:
  192.  
  193.                         AccountFoo/Folder/SubFolder/SubSubFolder
  194.                         /UnboundFolder/Child
  195.  
  196.                         See the example for details.
  197.  
  198.          What it does:
  199.  
  200.            ScanFolder locates the folder using the folderpath
  201.            parameter. If found, it scans the whole folder.
  202.            Scanning means that it creates an internal list of
  203.            messages that are in the folder. Only incoming messages
  204.            are scanned and processed.
  205.  
  206.            The purpose of the function is to make an index available
  207.            to other functions. For example if there are 400 incoming
  208.            and 600 outgoing message in the folder, ScanFolder
  209.            creates an internal list (index) that contains 400 elements.
  210.            Other functions can access the list using an index integer
  211.            in the range of 0 to 399 (0<=index<=399).
  212.  
  213.  
  214.        long GetMail(long index)
  215.  
  216.          Parameters:
  217.  
  218.            index = Zero-based index for the internal list created by
  219.                    ScanFolder
  220.  
  221.          What it does:
  222.  
  223.            GetMail takes the given index and loads the message that
  224.            is indexed through the index value into the properties
  225.            described below.
  226.  
  227.  
  228.        long DeleteMail(long index)
  229.  
  230.          Parameters:
  231.  
  232.            index = Zero-based index of mail to be deleted
  233.  
  234.          What it does:
  235.  
  236.            The mail with the given index is deleted. This
  237.            operation does NOT modify the index. Attempt
  238.            to delete a message twice will fail.
  239.            Attempt to access a deleted message will fail.
  240.  
  241.  
  242.        long DeleteMailUseTrash(long index)
  243.        long DeleteMailDoNotUseTrash(long index)
  244.  
  245.          Parameters:
  246.  
  247.            index = Zero-based index of mail to be deleted
  248.  
  249.          What it does:
  250.  
  251.            Same as DeleteMail but overrides the behavior
  252.            set in the account settings.
  253.            DeleteMailUseTrash behaves as if the option in the
  254.            account settings was not checked.
  255.            DeleteMailDoNotUseTrash deletes mail immedialety without
  256.            moving to the trash.
  257.  
  258.  
  259.        long MoveMail(long index,BSTR topath)
  260.        long CopyMail(long index,BSTR topath)
  261.  
  262.          Parameters:
  263.  
  264.            index  = Zero-based index of the mail to be moved/copied
  265.            topath = Full path to destination folder. See folderpath
  266.                     parameter of ScanFolder.
  267.  
  268.          What it does:
  269.  
  270.            The mail with the given index is moved/copied to the
  271.            destination folder. This operation does not modify
  272.            in index.
  273.  
  274.  
  275.      Properties:
  276.  
  277.        BSTR FromEmail
  278.  
  279.          After GetMail this property contains the email address of
  280.          the sender (for example 'gs@mynet.com').
  281.          The property is read-only. Writing to it will not cause an
  282.          exception but has no effect.
  283.  
  284.        BSTR FromRealName
  285.  
  286.          After GetMail this property contains the real name of the
  287.          sender (for example 'Gary Sanders'). Read-only.
  288.  
  289.        BSTR Subject
  290.  
  291.          After GetMail this property contains the subject of the mail.
  292.          This property is also used by group 1 functions.
  293.  
  294.        BSTR Body
  295.  
  296.          After GetMail this property contains the body of the mail.
  297.          Multiple lines are separated by 0x0D 0x0A.
  298.  
  299.          NOTE: This property is delayed. That means that GetMail
  300.                does not load the value immediately. The first reading
  301.                access to Body loads the value. So the speed of execution
  302.                is greatly increased because the body and header of a
  303.                mail is loaded on demand. If you do not need the body or
  304.                header information it is not loaded.
  305.  
  306.          This property is also used by group 1 functions.
  307.  
  308.        BSTR Header
  309.  
  310.          After GetMail this property contains the header of the mail.
  311.          Multiple lines are separated by 0x0D 0x0A.
  312.          Like Body the property is delayed.
  313.          This property is also used by group 1 functions.
  314.  
  315.        long MailCount
  316.  
  317.          After ScanFolder this property contains the number of
  318.          elements in the index. That is the number of
  319.          incoming messages in the folder.
  320.          Read-only.
  321.  
  322.      Example:
  323.  
  324.        akmobj.ScanFolder "MyAccount/Inbox/FromMyCustomerA"
  325.        '
  326.        ' You can access the special folder if the first character is
  327.        ' a '/'
  328.        '
  329.        ' akmobj.ScanFolder "/SpecialFolderXYZ"
  330.        '
  331.        for i=0 to akmobj.MailCount-1
  332.          akmobj.GetMail(i)
  333.          print akmobj.FromEmail
  334.          print akmobj.FromRealName
  335.          print akmobj.Subject
  336.          print akmobj.Body
  337.          print akmobj.Header
  338.        next i
  339.  
  340.  
  341.    3. Group: Functions to examine address books
  342.              Functions to create/delete entries
  343.  
  344.      Methods:
  345.  
  346.        long ScanBook(BSTR bookname)
  347.  
  348.          Parameters:
  349.  
  350.            bookname = String containing a name of a book
  351.  
  352.          What is does:
  353.  
  354.            ScanBook is the same as ScanFolder but for books.
  355.            The index used for books is completely independend
  356.            of the message index.
  357.  
  358.        long GetEntry(long index)
  359.  
  360.          Parameters:
  361.  
  362.            index = Zero-based index of the entry in the book index
  363.  
  364.          What it does:
  365.  
  366.            GetEntry loads the entry identified by the index into
  367.            the properties described below.
  368.  
  369.        long DeleteEntry(long index)
  370.  
  371.          Parameters:
  372.  
  373.            index = Zero-based index of entry to delete
  374.  
  375.          What it does:
  376.  
  377.            Deletes the entry identified by the index. This
  378.            operation does not modify the index.
  379.  
  380.  
  381.        long StoreNewEntry(BSTR bookname)
  382.  
  383.          Parameters:
  384.  
  385.            bookname = String containing a name of a book
  386.  
  387.          What it does:
  388.  
  389.            The function takes the values of the EntryName, EntryEmail,
  390.            EntryAlias, EntryComment properties described below
  391.            and creates a new entry of them. The new entry is
  392.            stored in the given book.
  393.  
  394.  
  395.      Properties:
  396.  
  397.        BSTR EntryName
  398.  
  399.          Name of the person stored in the entry
  400.  
  401.        BSTR EntryEmail
  402.  
  403.          Email address of the person stored in the entry
  404.  
  405.        BSTR EntryAlias
  406.  
  407.          Alias of the person stored in the entry
  408.  
  409.        BSTR EntryComment
  410.  
  411.          Comment of the person stored in the entry
  412.  
  413.        long EntryCount
  414.  
  415.          Number of entries in the book index. Read-only.
  416.  
  417.  
  418.      Example:
  419.  
  420.        ' This shows how to list all entries in a book
  421.        '
  422.        akmobj.ScanBook "MyBook"
  423.        for i=0 to akmobj.EntryCount-1
  424.          akmobj.GetEntry(i)
  425.          print akmobj.EntryName
  426.          print akmobj.EntryEmail
  427.          print akmobj.EntryAlias
  428.          print akmobj.EntryComment
  429.        next i
  430.  
  431.        ' This shows how to create a new entry
  432.        '
  433.        akmobj.EntryName="Andreas Kinzler"
  434.        akmobj.EntryEmail="akinzler@pobox.com"
  435.        akmobj.EntryAlias="ak"
  436.        akmobj.EntryComment="Author of AK-Mail"
  437.        akmobj.StoreNewEntry "MyBook"
  438.  
  439.  
  440. 4. Appendix A - Error Codes
  441.  
  442.     0 = Success
  443.     1 = AK-Mail is not registered, OLE Automation not available
  444.     2 = General Error
  445.     3 = Problem to resolve account name, no account with the given
  446.         name exists
  447.     4 = Cannot store new mail because the ToField property string is
  448.         empty
  449.     5 = Cannot store new mail because at least one email address is invalid
  450.     6 = Problem to resolve folder path, no such path or folder exists
  451.     7 = Problem to resolve book name, no book with the given name
  452.         exists
  453.     8 = Invalid index value
  454.     9 = Invalid entry alias
  455.    10 = Invalid entry email address
  456.    11 = Invalid entry name
  457.