email Client API

1
email Client API

• What does it do?
• How do you make it work?

2
Email Client API

• WHAT IT IS
• Gives applications the ability to customize an
  e-mail client according to the applications
  needs
• WHAT IT DOES
• Allows connection to a POP3 server and allows the
  application to take control when messages are
  received from the server
• Allows connection to an SMTP server to be able to
  send e-mails

3
email Client API Functions
include ltmailcapi.hgt

• MCCreate Function
• A new email client is created by calling
  MCCreate
• Parameters specify port and IP addresses of POP3
  and SMTP server.
• Returns handle if successful, otherwise 0.
• MCClose Function
• Closes out the email client.
• Closes associated sockets and reclaims memory.

4
POP3-oriented API Functions

• MCReadLogin log into POP3 server
• MCReadLogout log out of server
• MCDele delete a message from the server (DELE
  request)
• MC_get_msg_count get number of my messages on
  server
• MCStat get number of messages on server (STAT
  request)
• MCList request a list of messages from the
  server, or length of one message (LIST request)
• MCRegisterLIST register a callback function for
  data returned by server after a LIST request
• MCNoop sends the server NOOP
• MCRetr retrieve a specific message (by number
  RETR request)
• MCRegisterRETR register callback function for
  data returned by server after RETR request

5
POP3-oriented API Functions (2)

• MCRetrWithAttachments retrieve a message by
  number and 3 attachments
• MCRegisterRETRWithAttachments register a user
  callback to process data retrieved with
  attachments
• MCRset undeletes all my messages (RSET request)
• All POP3-oriented functions return 0 for success
  and 1 for failure.

6
SMTP-Oriented API Functions

• MCSendSimpleMail send an ASCII mail message to
  the SMTP server
• MCSendSimpleMailWithDomain send an ASCII mail
  message preceded by HELO with domain name
• MCSendMailWithAttachments sends an email with
  3 attachments
• All SMTP-oriented functions return 0 for success
  and 1 for failure.

7
Email APIs

• Support non-blocking feature
• Allow to send multiple mails simultaneously (No
  need to wait for mail to be completely sent
  before sending next mail)
• User callback function is needed for file
  attachment (to send and receive data)

8
Email APIs

• Header can be included in listing mail (slash \
  is used to separate each header field) and
  retrieving mail
• Old v5.1 email APIs become deprecated (except
  MCCreate and MCClose)
• Should use these new v6.0 email APIs

9
Email APIS

• int MCRegisterLogin(unsigned long handle,
  mc_client_callback_fn callback, unsigned long
  user_data)
• int MCUserLogin(unsigned long handle, char
  user, char pass, int wait)
• int MCUserLogout(unsigned long handle, int wait)
• int MCRegisterSummary(unsigned long handle,
  mc_list_callback_fn callback, unsigned long
  user_data)
• int MCSummary(unsigned long handle, int wait)
• int MCRegisterListMail(unsigned long handle,
  mc_list_callback_fn callback, unsigned long
  user_data)
• int MCListMail(unsigned long handle, int
  start_id, int end_id, char buffer, int bufsize,
  BOOLEAN includeHeader, int wait)

10
Email APIs

• int MCSetDomain(unsigned long handle, char
  domain)
• int MCSetSignature(unsigned long handle, char
  signature)
• int MCNewMail(unsigned long handle, unsigned long
  mail_id)
• int MCCancelMail(unsigned long handle, unsigned
  long mail_id)
• int MCAdd_ToAddr(unsigned long handle, unsigned
  long mail_id, char to_addr)
• int MCAdd_CopyAddr(unsigned long handle, unsigned
  long mail_id, char cc_addr)
• int MCRegisterSend_File(unsigned long handle,
  unsigned long mail_id, mc_file_callback_fn
  callback, unsigned long user_data)
• The callback function will be callback for each
  attachment.
• int MCAdd_Attachment(unsigned long handle,
  unsigned long mail_id, char filename, int
  file_type, unsigned int access_code)
• Filename will be passed to the mc_file_callback_fn
  callback function
• int MCRegisterSend(unsigned long handle, unsigned
  long mail_id, send_mail_callback_fn callback,
  unsigned long user_data)
• int MCSendMail(unsigned long handle, unsigned
  long mail_id, char from_addr, char to_addr,
  char subject, char bodybuf, int body_type,
  int wait)

11
Email APIs

• int MCRegisterRetr_File(unsigned long handle,
  mc_file_callback_fn callback, unsigned long
  user_data)
• Callback function will be indicated either the
  data is body message, or file attachment
  (BODY-MESSAGE or FILE-ATTACHMENT)
• Callback function will be called continuously
  until its given a NULL data pointer NULL size
  data pointer. It indicates end-of-file.
• int MCRegisterRetr(unsigned long handle,
  retr_mail_callback_fn callback, unsigned long
  user_data)
• int MCRetrMail(unsigned long handle, int msgId,
  char readBuffer, unsigned long readLength,
  BOOLEAN includeHeader, int wait)
• If readBuffer is NULL, body message will be
  treated as a file attachment. It means the
  callback function from MCRegisterRetr_File will
  be called with BODY-MESSAGE.
• If readBuffer is not NULL, it will contain the
  body message.

12
Email APIs

• int MCRegisterDel(unsigned long handle,
  mc_client_callback_fn callback, unsigned long
  user_data)
• int MCDeleteMail(unsigned long handle, int msgId,
  int wait)
• int MCUndeleteAll(unsigned long handle, int wait)

13
Email (File System)

• Send mail with file attachment from the file
  system.
• Retrieve and save mail and file attachment in the
  file system.

14
Email (File System)

• MCAdd_FileAttachment
• Attach files in the file system

15
Email (File System)

• MCRetrMail_Save
• Save the mail message and file attachment in the
  file system.
• Must not wait for mail to be saved if this
  function is initiated in Web Pages.
• MCRetrMail_Read
• Read mail message
• Copy the mail message in the users buffer
• Save any file attachment in the file system
• Must not wait if this function is initiated in
  Web Pages