Dallas Semiconductor DS80C400 C Libraries Home Page

Main Page | Modules | Data Structures | Directories | File List | Data Fields | Globals

tini400_pop3.h File Reference


Detailed Description

Pop3 Library functions for DS80C400 processor.

This library contains functions for receiving mails from pop3 mail server

For detailed information on the DS80C400 please see the High-Speed Microcontroller User's Guide: DS80C400 Supplement.

Warning:
The functions in this library are NOT multi-process safe--that is, if you call the same method from two different processes at the same time, the parameters to the function may be destroyed, yielding unpredictable results.

Go to the source code of this file.

Data Structures

struct  _mailheader
struct  _userheader
struct  _mail
struct  _maillist
struct  _pop3_session

Defines

#define MAX_LINE_SIZE   1024
#define POP3_VERSION   2
#define POP3_MAXATTACHMENTSIZE   5
#define POP3_MAXUSERHEADERSIZE   20
#define POP3_INSUFFICIENT_MEMORY   -1
#define POP3_RECEIVEMAIL_ERROR   -5
#define POP3_INVALID_MAILNUMBER   -6
#define POP3_SOCKET_ERROR   -7
#define POP3_INVALID_USER_PASSWORD   -10
#define POP3_LIBRARY_IS_NOT_CONFIGURED   -11
#define POP3_NOT_CONNECTED   -12
#define POP3_FILE_ERROR   -13
#define POP3_STATUS_SUCCESS   0

Typedefs

typedef _mailheader mailheader
typedef _userheader userheader
typedef _mail mail
typedef _maillist maillist
typedef _pop3_session pop3_session

Functions

void pop3_init (void)
 Initializes pop3 library.
void pop3_setuserheaderlist (struct _userheader *pusrhdr)
 Sets user defined mail header list.
int pop3_login (long pop3_host, char *username, char *pwd)
 Login to pop3 server.
int pop3_deletemail (int mailnumber)
 Deletes mail from pop3 mailbox.
int pop3_getmailboxstate (int *numberofmails, long *total_size)
 Gets number of mails and mailbox size value from pop3 server.
_mailpop3_receivemail (int mailnumber, int *status)
 Receives mail from pop3 mail server.
_maillistpop3_getmaillist (int *status)
 Reads mail list from pop3 server.
int pop3_logout (void)
 Terminates connection from pop3 server.
void pop3_registerauthcallback (int(*funpt)())
 Registers pop3 authentication callback routine.


Define Documentation

#define MAX_LINE_SIZE   1024
 

Definition for maximum size of mail header

#define POP3_FILE_ERROR   -13
 

File creation error value, This value is returned if there is any error in opening file

See also:
pop3_receivemail

#define POP3_INSUFFICIENT_MEMORY   -1
 

Insufficient memory error value

See also:
pop3_receivemail

pop3_login

pop3_getmaillist

#define POP3_INVALID_MAILNUMBER   -6
 

Invalid mail number error value

See also:
pop3_receivemail

#define POP3_INVALID_USER_PASSWORD   -10
 

Invalid User or Password error value

See also:
pop3_login

#define POP3_LIBRARY_IS_NOT_CONFIGURED   -11
 

pop3 library is not configured error value, this value will be returned if pop3 host information is not configured

See also:
pop3_login

#define POP3_MAXATTACHMENTSIZE   5
 

Definition for maximum number of attachments

See also:
pop3_receivemail

#define POP3_MAXUSERHEADERSIZE   20
 

Definition for maximum number of user headers

See also:
pop3_receivemail

#define POP3_NOT_CONNECTED   -12
 

This error value is returned if connection was not established with pop3 server.

See also:
pop3_deletemail

pop3_getmailboxstate

pop3_getmaillist

pop3_receivemail

pop3_logout

#define POP3_RECEIVEMAIL_ERROR   -5
 

Receive mail error value

See also:
pop3_receivemail

#define POP3_SOCKET_ERROR   -7
 

Socket error value

See also:
pop3_receivemail

pop3_login

pop3_logout

pop3_getmailboxstate

pop3_getmaillist

#define POP3_STATUS_SUCCESS   0
 

pop3 Status success value, this value is returned when operation is completed successfully.

See also:
pop3_receivemail

#define POP3_VERSION   2
 

Version number associated with this header file. Should be the same as the version number returned by the pop3_version function.

See also:
pop3_version


Typedef Documentation

typedef struct _mail mail
 

Structure for mail that contains standard mail header, user mail header, message and attachment filename list

typedef struct _mailheader mailheader
 

Structure for standard mail header holds standard mail header values

typedef struct _maillist maillist
 

Structure for maillist

typedef struct _pop3_session pop3_session
 

Structure for pop3_session

typedef struct _userheader userheader
 

Structure for user defined mail header contains user header name list and user header value list


Function Documentation

int pop3_deletemail int  mailnumber  ) 
 

Deletes mail from pop3 mailbox.

This function sets delete mark against the input message number. The server will delete all the messages marked with delete mark after disconnecting from client. pop3 login operation must be performed before calling this function.

Parameters:
mailnumber Message number to set delete mark
Returns:
POP3_STATUS_SUCCESS, if everything is successful. Otherwise, one of the following error values:
See also:
pop3_getmaillist

pop3_receivemail

int pop3_getmailboxstate int *  numberofmails,
long *  total_size
 

Gets number of mails and mailbox size value from pop3 server.

This function returns number of messages in mailbox and returns total size of the message. pop3 login operation must be performed before calling this function.

Parameters:
numberofmails points to address location where number of mails value will be stored
total_size points to address location where total mailsize value will be stored
Returns:
POP3_STATUS_SUCCESS, if everything is successful. Otherwise, one of the following error values:
See also:
pop3_getmaillist

pop3_receivemail

struct _maillist* pop3_getmaillist int *  status  ) 
 

Reads mail list from pop3 server.

This function returns list of mail numbers and size of each mail. pop3 login operation must be performed before calling this function.

Parameters:
status points to address location where status of pop3 function will be stored
Returns:
NULL if pop3_getmaillist failed. Otherwise, returns pointer to maillist object
See also:
pop3_login

pop3_logout

pop3_getmailboxstate

pop3_deletemail

void pop3_init void   ) 
 

Initializes pop3 library.

This function initializes the internal data structures of pop3 library. This function should be called first before calling any other functions of pop3 library

int pop3_login long  pop3_host,
char *  username,
char *  pwd
 

Login to pop3 server.

This function performs authentication with pop3 server and enters into transaction state. It does plain text authentication by default. user can override authentication method by registering their own authentication callback through pop3_registerauthcallback function.

Parameters:
pop3_host IP4 address structure, return value of in_addr
username user name value
pwd password value
Returns:
POP3_STATUS_SUCCESS if the operation is completed successfully. Otherwise, one of the following error values:
See also:
pop3_logout

int pop3_logout void   ) 
 

Terminates connection from pop3 server.

This function terminates connection with pop3 server. If pop3 login operation was not performed, it returns error.

Returns:
POP3_STATUS_SUCCESS, if everything is successful. Otherwise, one of the following error values:
See also:
pop3_login

struct _mail* pop3_receivemail int  mailnumber,
int *  status
 

Receives mail from pop3 mail server.

This function receives mail from POP3 server and returns pointer to mail object that contains standard mailheader value, user mail header value, message and attachment file list for received mail. this function supports both base64 and quoted-printable encryption/decryption types for both attachments and message. all the attachments will be directly stored in filesystem and mail object retains filenames of attachments.

NOTE: Memory for returned mailobject is allocated by this function. If user will not free the memory, then, the memory for mailobject will be re-allocated when pop3_receivemail function is called next time

NOTE: User mail header name list should be set to retrieve user mail header values. Otherwise, this function will ignore user mail header values.

Parameters:
mailnumber Message number of mail to retrieve
status points to address location where status of pop3 function will be stored
Returns:
NULL if pop3_receivemail function failed. Otherwise, returns pointer to mail object
See also:
pop3_login

pop3_logout

pop3_getmaillist

pop3_deletemail

void pop3_registerauthcallback int(*)()  funpt  ) 
 

Registers pop3 authentication callback routine.

This function registers user defined authentication callback function with pop3 library. when pop3_login function is called from application, user authentication routine will be called with pop3_session object parameter that contains username,password and socket handler.

NOTE: User authentication callback function has to have the following function prototype to receive pop3_session structure pointer.

int [authentication call back function name] (pop3_session *pop3_handle)

NOTE: User authentication callback routine should return POP3_STATUS_SUCCESS value for successful authentication. for invalid user or password, POP3_INVALID_USER_PASSWORD error value should be returned.

See also:
pop3_login

pop3_session

void pop3_setuserheaderlist struct _userheader pusrhdr  ) 
 

Sets user defined mail header list.

This function stores address of user mail header list structure in pop3 library global variable. the user mail header value will be retrieved for all user defined mail header names.

Parameters:
pusrhdr pointer to the user mail header list. if user mail header name list is less than POP3_MAXUSERHEADERSIZE, the last item of user mail header namelist should be NULL.
See also:
pop3_receivemail


Copyright 2005 Dallas Semiconductor, Inc.. Documentation generated by Doxygen.