home *** CD-ROM | disk | FTP | other *** search
/ Hot Shareware 35 / hot35.iso / ficheros / LC / SEE4C10.ZIP / SEE4C_R.TXT < prev    next >
Text File  |  1998-05-26  |  21KB  |  723 lines
  1.  
  2.  
  3.  
  4.  
  5.                            SMTP Email Engine
  6.  
  7.                            Library for C/C++
  8.  
  9.                                  (SEE4C)
  10.  
  11.  
  12.                             REFERENCE MANUAL
  13.  
  14.  
  15.  
  16.                                Version 1.0
  17.  
  18.                                June 1, 1998
  19.  
  20.  
  21.  
  22.  
  23.                      This software is provided as-is.
  24.               There are no warranties, expressed or implied.
  25.  
  26.  
  27.  
  28.  
  29.                          Copyright (C) 1998
  30.                            All rights reserved
  31.  
  32.  
  33.  
  34.                        MarshallSoft Computing, Inc.
  35.                            Post Office Box 4543
  36.                            Huntsville AL 35815
  37.  
  38.  
  39.                            Voice : 256-881-4630
  40.                              FAX : 256-880-0925
  41.                            email : info@marshallsoft.com
  42.                              web : www.marshallsoft.com
  43.  
  44.                                _______
  45.                           ____|__     |                (R)
  46.                        --+       |    +-------------------
  47.                          |   ____|__  |  Association of
  48.                          |  |       |_|  Shareware
  49.                          |__|   o   |    Professionals
  50.                        --+--+   |   +---------------------
  51.                             |___|___|    MEMBER
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.      SEE4C Reference Manual                                    Page 1
  61.  
  62.                             C O N T E N T S
  63.  
  64.  
  65.  
  66.         Chapter                                     Page
  67.  
  68.         Table of Contents.............................2
  69.  
  70.         General Remarks...............................3
  71.  
  72.         SEE Functions.................................3
  73.  
  74.            seeClose...................................3
  75.  
  76.            seeConnectTo...............................4
  77.  
  78.            seeDriver..................................5
  79.  
  80.            seeErrorText...............................6
  81.  
  82.            seeIntegerParam............................7
  83.  
  84.            seeSendEmail...............................8
  85.  
  86.            seeStatistics..............................9
  87.  
  88.            seeStringParam............................10
  89.  
  90.            seeVerifyFormat...........................11
  91.  
  92.         SEE Error Codes..............................12
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.      SEE4C Reference Manual                                    Page 2
  121.  
  122.       General Remarks
  123.  
  124.       All functions return an integer code. Negative values are always
  125.       errors. See section "SEE Error Codes". Non-negative return codes are
  126.       never errors.
  127.  
  128.       Allocate all buffers passed to SEE statically, rather than
  129.       dynamically on the stack. You can always force any variable
  130.       declaration to be staticslly allocated by use of the "static"
  131.       keyword, for example:
  132.  
  133.           static char Buffer[64];
  134.  
  135.  
  136.       SEE Functions
  137.  
  138.  
  139.       +----------+--------------------------------------------------------+
  140.       | seeClose | Closes SMTP Email Engine.                              |
  141.       +----------+--------------------------------------------------------+
  142.  
  143.  
  144.         SYNTAX  int seeClose(void)
  145.  
  146.        REMARKS  The seeClose function closes the connection created by
  147.                 calling seeConnectTo. seeConnectTo can be called again to
  148.                 open a connection to another SMTP server if desired.
  149.  
  150.                 Normally, there is only one seeConnectTo and one seeClose
  151.                 in your program.
  152.  
  153.        RETURNS  < 0 : An error has occured. See the error list.
  154.  
  155.        EXAMPLE
  156.  
  157.                 // call after sending all email.
  158.  
  159.                 seeClose();
  160.  
  161.       ALSO SEE  seeConnectTo.
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.      SEE4C Reference Manual                                    Page 3
  181.  
  182.  
  183.       +--------------+----------------------------------------------------+
  184.       | seeConnectTo | Connects to SMTP server.                           |
  185.       +--------------+----------------------------------------------------+
  186.  
  187.  
  188.         SYNTAX  int seeConnectTo(
  189.                          LPSTR Server,  // SMTP server.
  190.                          LPSTR From,    // Your email address in brackets.
  191.                          LPSTR ReplyTo) // Email address to reply to.
  192.  
  193.        REMARKS  The seeConnectTo function establishes a connection with the
  194.                 SMTP server as specified by the Server argument.
  195.  
  196.                 Your SMTP server name will typically be named
  197.                 "mail.XXX.com" where XXX is your email address, such as
  198.                 name@XXX.com. Your SMTP server name can also be found in
  199.                 the setup information for your normal email client, such as
  200.                 Eudora or Microsoft Outlook.
  201.  
  202.                 The SMTP server name can also be specified in dotted
  203.                 decimal notation if wanted. For example "10.23.231.1".
  204.  
  205.                 The From string is required and must be enclosed in "<>"
  206.                 brackets, such as <mike@marshallsoft.com>.
  207.  
  208.                 The ReplyTo string is optional and is used for the
  209.                 "Reply-To:" header line. If used, the email address must be
  210.                 enclosed in "<>" brackets.
  211.  
  212.  
  213.        RETURNS  < 0 : An error has occured. See the error list.
  214.  
  215.        EXAMPLE
  216.  
  217.                 seeConnect("mail.myisp.com",   // my SMTP server
  218.                            "<me@myisp.com>",   // my email address
  219.                            NULL);              // no Reply-To
  220.  
  221.                 seeConnect("mail.myisp.com",   // my SMTP server
  222.                            "<me@myisp.com>",   // my email address
  223.                            "<him@himisp.com>;  // Reply-To address
  224.  
  225.       ALSO SEE  seeClose.
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.      SEE4C Reference Manual                                    Page 4
  241.  
  242.  
  243.       +-----------+-------------------------------------------------------+
  244.       | seeDriver | Executes next SEE state.                              |
  245.       +-----------+-------------------------------------------------------+
  246.  
  247.  
  248.         SYNTAX  int seeDriver(void)
  249.  
  250.        REMARKS  The seeDriver function executes the next state in SEE16.DLL
  251.                 or SEE32.DLL after calling seeConnectTo, seeSendEmail, or
  252.                 seeClose provided that the AUTO_DRIVER_CALL flag is
  253.                 disabled.
  254.  
  255.                 The purpose of this function is to allow the programmer to
  256.                 get control after the driver executes each state.
  257.  
  258.        RETURNS  = 0 : The driver is done.
  259.                 < 0 : An error has occured. See the error list.
  260.                 > 0 : The returned value is the state just executed.
  261.  
  262.        EXAMPLE
  263.  
  264.                 int Code;
  265.                 . . .
  266.                 [call seeConnectTo]
  267.                 . . .
  268.                 // disable automatic calling of seeDriver().
  269.                 seeIntegerParam(AUTO_DRIVER_CALL, 0);
  270.                 Code = seeSendEmail(...);
  271.                 if(Code<0)
  272.                   {printf("Error %d\n", Code);
  273.                    exit(1);
  274.                   }
  275.                 while(1)
  276.                   {Code = seeDriver();
  277.                    if(Code<0)
  278.                      {printf("Error %d\n", Code);
  279.                       exit(1);
  280.                      }
  281.                    /* display all but "wait" state */
  282.                    if(Code!=9999) printf("%d ",Code);
  283.                    if(Code==0) return 0;
  284.                   }
  285.                }
  286.  
  287.       ALSO SEE  seeIntegerParam
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.      SEE4C Reference Manual                                    Page 5
  301.  
  302.  
  303.       +--------------+----------------------------------------------------+
  304.       | seeErrorText | Get text associated with error code.               |
  305.       +--------------+----------------------------------------------------+
  306.  
  307.  
  308.         SYNTAX  int seeErrorText(
  309.                         int Code,   // Error code returned by SEE function.
  310.                       LPSTR Buffer, // Buffer to place error text into.
  311.                         int BufLen) // Length of above Buffer.
  312.  
  313.        REMARKS  The seeErrorText function is used to get the error text
  314.                 associated with an an error code as returned by
  315.                 selConnectTo, seeSendEmail, seeClose, or seeDriver.
  316.  
  317.                 When an error occurs, seeErrorText can be used to get the
  318.                 error text so that it can be displayed for the user.
  319.  
  320.        EXAMPLE
  321.  
  322.                 static char Buffer[80];
  323.  
  324.                 . . .
  325.  
  326.                 Code = seeConnectTo("mail.myserver.com",
  327.                                     "<me@myisp.net>",
  328.                                     NULL);
  329.                 if(Code<0)
  330.                   {seeErrorText(Code,Buffer,80);
  331.                    printf("ERROR %d: %s\n", Code, Buffer);
  332.                    exit(1);
  333.                   }
  334.  
  335.       ALSO SEE
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.      SEE4C Reference Manual                                    Page 6
  361.  
  362.  
  363.       +-----------------+-------------------------------------------------+
  364.       | seeIntegerParam | Sets SEE integer parameter.                     |
  365.       +-----------------+-------------------------------------------------+
  366.  
  367.  
  368.         SYNTAX  int seeIntegerParam(
  369.                          int ParmIndex,  // Parameter index (see below).
  370.                        ULONG ParmValue)  // Value of parameter to set.
  371.  
  372.        REMARKS The seeIntegerParam is used to set an integer parameter as
  373.                 defined in SEE.H. For more information, refer to the Users
  374.                 Manual. All times are in milliseconds.
  375.  
  376.                         Parameter Name     Default
  377.                  SEE_MIN_RESPONSE_WAIT  :  500
  378.                  SEE_MAX_RESPONSE_WAIT  :  10000
  379.                      SEE_MIN_LINE_WAIT  :  5
  380.                      SEE_MAX_LINE_WAIT  :  10000
  381.                       SEE_CONNECT_WAIT  :  60000
  382.                   SEE_QUOTED_PRINTABLE  :  0
  383.                   SEE_AUTO_CALL_DRIVER  :  1
  384.  
  385.                 SEE_MIN_RESPONSE_WAIT is the delay before looking for the
  386.                 server's response.
  387.  
  388.                 SEE_MAX_RESPONSE_WAIT is the time after which a "time-out"
  389.                 error ocurrs if the server has not responded.
  390.  
  391.                 SEE_MIN_LINE_WAIT is the delay before checking if the
  392.                 server is ready to accept the next line of input.
  393.  
  394.                 SEE_MAX_LINE_WAIT is the time after which a "time-out"
  395.                 error is declared if the server has not responded.
  396.  
  397.                 SEE_CONNECT_WAIT is the maximum time allowed to complete a
  398.                 connection to the SMTP server.
  399.  
  400.                 SEE_QUOTED_PRINTABLE controls the whether messages are (1)
  401.                 or are not (0) encoded as quoted-printable.
  402.  
  403.                 SEE_AUTO_CALL_DRIVER controls whether ssDriver is called
  404.                 automatically (to completion) after seeConnectTo,
  405.                 seeSendEmail, or seeClose is called.
  406.  
  407.        EXAMPLE
  408.  
  409.                 /* disable auto call feature */
  410.                 seeIntegerParam(SEE_AUTO_CALL_DRIVER, 0);
  411.  
  412.       ALSO SEE  seeStringParam.
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.      SEE4C Reference Manual                                    Page 7
  421.  
  422.  
  423.       +--------------+----------------------------------------------------+
  424.       | seeSendEmail | Sends email and attachments.                       |
  425.       +--------------+----------------------------------------------------+
  426.  
  427.  
  428.         SYNTAX  int seeSendEmail(
  429.                          LPSTR To,     // Receipient, separated by commas.
  430.                          LPSTR CC,     // CC list, separated by commas.
  431.                          LPSTR BCC,    // BCC list, separated by commas.
  432.                          LPSTR Subj,   // Subject text.
  433.                          LPSTR Msg,    // Message or message filename.
  434.                          LPSTR Attach) // File attachment.
  435.  
  436.        REMARKS  The seeSendEmail function is used to send email once a
  437.                 conection has been made to your SMTP server after calling
  438.                 seeConnectTo.
  439.  
  440.                 Note that all email addresses (in To, CC, and BCC strings)
  441.                 must be bracketed. For example:
  442.  
  443.                      <mike@marshallsoft.com>
  444.  
  445.                 The CC and BCC strings may contain multiple email
  446.                 addresses, separted by commas. For example:
  447.  
  448.                 "Billy Bob<bbob@isp.com>,Buster<bm@isp.com>"
  449.  
  450.                 If the first character of the message (fifth argument) is
  451.                 a '@', then it is considered as the filename which contains
  452.                 the message to send.
  453.  
  454.        RETURNS  < 0 : An error has occured. See the error list.
  455.  
  456.        EXAMPLE
  457.  
  458.               seeSendEmail("<myfriend@hisisp.com>",  /* receipient */
  459.                            NULL,                     /* CC list */
  460.                            NULL,                     /* BCC list */
  461.                            "Hello",                  /* subject */
  462.                            "Call me ASAP!",          /* message */
  463.                            NULL);                    /* attachment */
  464.  
  465.  
  466.       ALSO SEE seeConnectTo
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.      SEE4C Reference Manual                                    Page 8
  481.  
  482.  
  483.       +---------------+---------------------------------------------------+
  484.       | seeStatistics | Returns runtime statistics.                       |
  485.       +---------------+---------------------------------------------------+
  486.  
  487.  
  488.         SYNTAX  ULONG seeStatistics(
  489.                            int Index)   // Specifies which statistic.
  490.  
  491.        REMARKS  The seeStatistics function is used to return runtime
  492.                 statistics in the SEE DLL. The values of Index are defined
  493.                 in SEE.H as follows:
  494.  
  495.                    SEE_GET_SOCK_ERROR : Gets last socket error.
  496.                       SEE_GET_COUNTER : Gets # times driver called.
  497.                      SEE_GET_RESPONSE : Gets last SMTP response code.
  498.  
  499.                 SEE_GET_MESSAGE_BYTES_READ : Gets # message bytes read.
  500.                  SEE_GET_ATTACH_BYTES_READ : Gets # attachment bytes read.
  501.                   SEE_GET_TOTAL_BYTES_READ : Gets total of above two.
  502.  
  503.                 SEE_GET_MESSAGE_BYTES_SENT : Gets # message bytes sent.
  504.                  SEE_GET_ATTACH_BYTES_SENT : Gets # attachment bytes sent.
  505.                   SEE_GET_TOTAL_BYTES_SENT : Gets total of above two.
  506.  
  507.                 The number of message bytes sent will usually be larger
  508.                 than your message size because of SMTP protocol overhead.
  509.  
  510.                 The number of attachment bytes sent will be at least
  511.                 one-third larger than the actual attachment since every 3
  512.                 bytes are encoded as 4 7-bit ASCII bytes before being
  513.                 transmitted.
  514.  
  515.                 The purpose of "...BYTES_READ" and "...BYTES_SENT" is to
  516.                 provide the ability to track the tranmission progress of
  517.                 large messages and attachments. See the DRIVER example
  518.                 program.
  519.  
  520.        EXAMPLE
  521.  
  522.                 // get total message & attachment bytes transmitted.
  523.  
  524.                 Code = seeStatistics(SEE_GET_TOTAL_BYTES_SENT);
  525.  
  526.       ALSE SEE  seeDriver, seeIntegerParam and seeStringParam.
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.      SEE4C Reference Manual                                    Page 9
  541.  
  542.  
  543.       +----------------+--------------------------------------------------+
  544.       | seeStringParam | Sets SEE string parameter.                       |
  545.       +----------------+--------------------------------------------------+
  546.  
  547.  
  548.         SYNTAX  int seeStringParam(
  549.                          int ParamName,    // Index of parameter.
  550.                        LPSTR ParamString)  // Parameter string.
  551.  
  552.        REMARKS  The seeStringParam function is used to set a string
  553.                 parameter as defined in SEE.H. For more information, refer
  554.                 to the Users Manual.
  555.  
  556.                 SEE_LOG_FILE : Specifies the log filename.
  557.  
  558.                 The log file is used to debug a SMTP session. Be advised
  559.                 that log files can be quite large. Don't use them unless
  560.                 neccessary.
  561.  
  562.        EXAMPLE
  563.  
  564.                 seeStringParam(SEE_LOG_FILE, "mytest.log");
  565.  
  566.       ALSO SEE seeIntegerParam
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.      SEE4C Reference Manual                                    Page 10
  601.  
  602.  
  603.       +-----------------+-------------------------------------------------+
  604.       | seeVerifyFormat | Check email address format.                     |
  605.       +-----------------+-------------------------------------------------+
  606.  
  607.  
  608.         SYNTAX  int seeVerifyFormat(
  609.                          LPSTR String)   // Email address to check.
  610.  
  611.        REMARKS  The seeVerifyFormat function is use to test an individual
  612.                 email address for proper formatting. If this function
  613.                 returns 0 or above, then the email address is properly
  614.                 formatted. But, if this function returns a negative value,
  615.                 the email address is either badly formatted, or it uses
  616.                 characters (such as '%') that are not normally used as part
  617.                 of an email address.
  618.  
  619.                 Note that left and right brackets ('<' and '>') must
  620.                 surround the email address.
  621.  
  622.        EXAMPLE
  623.  
  624.                 static char Buffer[80];
  625.  
  626.                 . . .
  627.  
  628.                 Code = seeVerifyFormat("Billy E. Bob<beb@hisasp.com>");
  629.                 if(Code<0)
  630.                   {seeErrorText(Code,Buffer,80);
  631.                    printf("Email address error : %s\n", Buffer);
  632.                    exit(1);
  633.                   }
  634.  
  635.       ALSO SEE seeErrorText
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.      SEE4C Reference Manual                                    Page 11
  661.  
  662.                           SEE Error Codes
  663.  
  664.  
  665.  
  666.  
  667.       +-----------------------+-----------------------------------------+
  668.       | SEE_NO_ERROR          | No error.                               |
  669.       | SEE_CANNOT_COMPLY     | Cannot comply. Not always an error.     |
  670.       +-----------------------+-----------------------------------------+
  671.       | SEE_EOF               | End of file (socket has been closed).   |
  672.       | SEE_IS_BLOCKING       | Socket is currently blocking.           |
  673.       | SEE_BAD_DOTTED        | Bad dotted address.                     |
  674.       | SEE_TIMED_OUT         | Socket timed out awaiting data.         |
  675.       | SEE_ABORTED           | The DLL has been corrupted.             |
  676.       | SEE_ALREADY_CONNECTED | Already connected to server.            |
  677.       | SEE_BACK_OVERFLOW     | Response buffer has overflowed.         |
  678.       | SEE_BAD_ADDRESS_CHAR  | Bad character in email address.         |
  679.       | SEE_CANNOT_ATTACH     | Cannot access WINSOCK                   |
  680.       | SEE_CANNOT_OPEN       | Cannot open file.                       |
  681.       | SEE_CONNECT_ERROR     | Error attempting to connect.            |
  682.       | SEE_EMPTY_ADDRESS     | EMPTY email address.                    |
  683.       | SEE_FROM_NULL_ARG     | FromPtr is NULL.                        |
  684.       | SEE_MISSING_AT_CHAR   | Missing '@' character in email address. |
  685.       | SEE_MISSING_FROM      | Missing FROM email address.             |
  686.       | SEE_MISSING_LEFT      | Missing '<' delimiter in email address. |
  687.       | SEE_MISSING_RIGHT     | Missing '>' terminating email address.  |
  688.       | SEE_NOT_CONNECTED     | Not connected to server                 |
  689.       | SEE_NO_RECEIPIENTS    | Must have at least one receipient.      |
  690.       | SEE_NO_SERVER         | Cannot find Smtp server.                |
  691.       | SEE_NULL_POINTER      | Unexpected NULL pointer.                |
  692.       | SEE_RCPT_NULL_ARG     | ToPtr is NULL.                          |
  693.       | SEE_SMTP_ERROR        | SMTP returned error.                    |
  694.       | SEE_SMTP_NULL_ARG     | SMTP Server not specified.              |
  695.       | SEE_SOCK_READ_ERROR   | Socket read error.                      |
  696.       | SEE_SOCK_WRITE_ERROR  | Socket write error.                     |
  697.       | SEE_TOO_MANY_AT_CHARS | Too many '@' symbols in email address.  |
  698.       +-----------------------+-----------------------------------------+
  699.  
  700.       NOTES:
  701.  
  702.       (1) All error codes are negative.
  703.       (2) Numerical error codes are defined in DEFINES.H.
  704.       (3) SEE_ABORTED will be returned if the DLL has been modified. You
  705.           should never get this message!
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.      SEE4C Reference Manual                                    Page 12
  721.  
  722.  
  723.