tini400_pop3.h

TINI的pop3的c代码

/* --------------------------------------------------------------------------------------
 *  Copyright (C) 2003 Dallas Semiconductor Corporation, All Rights Reserved.
 * 
 *  Permission is hereby granted, free of charge, to any person obtaining a
 *  copy of this software and associated documentation files (the "Software"),
 *  to deal in the Software without restriction, including without limitation
 *  the rights to use, copy, modify, merge, publish, distribute, sublicense,
 *  and/or sell copies of the Software, and to permit persons to whom the
 *  Software is furnished to do so, subject to the following conditions:
 * 
 *  The above copyright notice and this permission notice shall be included
 *  in all copies or substantial portions of the Software.
 * 
 *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 *  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 *  MERCHANTABILITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 *  IN NO EVENT SHALL DALLAS SEMICONDUCTOR BE LIABLE FOR ANY CLAIM, DAMAGES
 *  OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 *  ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 *  OTHER DEALINGS IN THE SOFTWARE.
 * 
 *  Except as contained in this notice, the name of Dallas Semiconductor
 *  shall not be used except as stated in the Dallas Semiconductor
 *  Branding Policy.
 */

/****************************************************************************************
 *		Module Name : pop3 library
 *		Description : pop3 library function declarations 
 *	   	   Filename : pop3.h
 *	Dependant Files : no dependant files
 *		   Compiler : keil C51 Compiler V7.06
 *			Version : Version 1.0
 *	  Modifications :
 *			  Notes :
 ***************************************************************************************/

#ifndef __rom400_pop3_
#define __rom400_pop3_

/** \file tini400_pop3.h
 *  \brief 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
 *  <a href="http://pdfserv.maxim-ic.com/arpdf/Design/DS80C400UG.pdf">
 *  High-Speed Microcontroller User's Guide: DS80C400 Supplement</a>.
 *
 *  \warning  The functions in this library are <b>NOT</b> 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.
 */

/** Definition for maximum size of mail header
*/
#define MAX_LINE_SIZE 1024

/** Version number associated with this header file.  Should be the same as
 * the version number returned by the <i>#pop3_version</i> function.
 * \sa #pop3_version */
#define POP3_VERSION 				2

/** Definition for maximum number of attachments
 * \sa #pop3_receivemail */
#define POP3_MAXATTACHMENTSIZE  	5

/** Definition for maximum number of user headers
 * \sa #pop3_receivemail */
#define POP3_MAXUSERHEADERSIZE    20

//Error values definition
/** Insufficient memory error value
* \sa #pop3_receivemail, #pop3_login, #pop3_getmaillist 
*/
#define POP3_INSUFFICIENT_MEMORY  -1

/** Receive mail error value
 * \sa #pop3_receivemail */
#define POP3_RECEIVEMAIL_ERROR    -5

/** Invalid mail number error value
 * \sa #pop3_receivemail */
#define POP3_INVALID_MAILNUMBER   -6

/** Socket error value
 * \sa #pop3_receivemail, #pop3_login , #pop3_logout
 *  #pop3_getmailboxstate, #pop3_getmaillist */
#define POP3_SOCKET_ERROR			-7

/** Invalid User or Password error value
 * \sa #pop3_login */
#define POP3_INVALID_USER_PASSWORD     -10 

/** pop3 library is not configured error value, this value will be returned if pop3 host information
is not configured
 * \sa #pop3_login */
#define POP3_LIBRARY_IS_NOT_CONFIGURED -11

/** This error value is returned if connection was not established with pop3 server.
 * \sa #pop3_deletemail, #pop3_getmailboxstate, #pop3_getmaillist, 
  #pop3_receivemail, #pop3_logout 
 */
#define POP3_NOT_CONNECTED    -12

/** File creation error value, This value is returned if there is any error in opening file
 * \sa #pop3_receivemail */
#define POP3_FILE_ERROR            -13

/** pop3 Status success value, this value is returned when operation is completed successfully.
 * \sa #pop3_receivemail */
#define POP3_STATUS_SUCCESS 		 0

/**
 * Structure for standard mail header holds standard mail header values
 */
typedef struct _mailheader
{
	char *from_id;					///<string contains from id mailheader value
	char *sendername;				///<string contains sendername mailheader value
	char *to_id;					///<string contains to id mailheader value
	char *recipientname;			///<string contains recipientname mailheader value
	char *subject;					///<string contains subject mailheader value
	char *reply_to_id;				///<string contains reply_to_id mailheader value
	char *cc_id;					///<string contains cc_id mailheader value
	char *bcc_id;					///<string contains bcc_id mailheader value
	char *errors_to_id;				///<string contains errors_to_id mailheader value
	char *date;						///<string contains date mailheader value
} mailheader;

/**
 * Structure for user defined mail header contains user header name list and user header value list
 */
typedef struct _userheader
{
	char *headernamelist[POP3_MAXUSERHEADERSIZE];   ///<array of string contains user mail header name list
	char *headervaluelist[POP3_MAXUSERHEADERSIZE];  ///<array of string contains user mail header value list
} userheader;

/**
 * Structure for mail that contains standard mail header, user mail header, message and attachment filename list
 */
typedef struct _mail
{
	struct _mailheader mailhdr;        ///<standard mailheader structure contains standard mail header values
	struct _userheader userhdr;        ///<user mailheader structure contains user defined mail header name list and value list
	char *msg;						   ///<string holds mail message
	char *attachmentlist[POP3_MAXATTACHMENTSIZE]; ///<array of string contains attachment file list
} mail;

/**
 * Structure for maillist
 */
typedef struct _maillist
{
	int numberofmails;     ///<number of mails value
	int *mailnumberlist;   ///<array of integers with mail number list
	int *mailsizelist;     ///<array of integers with size of each mail 
} maillist;

/**
 * Structure for pop3_session
 */
typedef struct _pop3_session{
	unsigned int handle;  ///<socket handler
	char *user;           ///<username value
	char *pass;           ///<password value
	int status;		      ///<status of pop3 session   
	int (*pop3_authentication)(); ///<address of pop3 authentication callback function
} pop3_session;

/**
 * \brief        Returns the version number of pop3 library
 *
 * \return       Version number of pop3 library.
 */
unsigned int pop3_version(void);

/**
 * \brief      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
 */
void pop3_init(void);

/**
 * \brief    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.
 *
 * \param     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.
 *
 * \sa        #pop3_receivemail
 */
void pop3_setuserheaderlist(struct _userheader *pusrhdr);

/**
 * \brief      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.
 *
 * \param     pop3_host  IP4 address structure, return value of in_addr
 * \param     username - user name value
 * \param	  pwd - password value
 *
 * \return    
 *	   #POP3_STATUS_SUCCESS - if the operation is completed successfully
 *	   Otherwise, one of the following error values
 *
 *          #POP3_LIBRARY_IS_NOT_CONFIGURED 
 *          #POP3_INSUFFICIENT_MEMORY
 *          #POP3_SOCKET_ERROR
 *          #POP3_RECEIVEMAIL_ERROR
 *          #POP3_INVALID_USER_PASSWORD
 *
 * \sa      #pop3_logout
 */
int pop3_login(long pop3_host, char *username, char *pwd);

/**
 * \brief      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.
 *
 * \param     mailnumber  -  Message number to set delete mark
 *
 * \return    
 *    #POP3_STATUS_SUCCESS, if everything is successful
 *    Otherwise, one of the following error values
 *       
 *       #POP3_NOT_CONNECTED
 *       #POP3_RECEIVEMAIL_ERROR
 *       #POP3_INVALID_MAILNUMBER
 *
 * \sa   #pop3_getmaillist
 * \sa   #pop3_receivemail
 */
int  pop3_deletemail(int mailnumber);

/**
 * \brief  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.
 *
 * \param  numberofmails - points to address location where number of mails value will be stored
 * \param  total_size - points to address location where total mailsize value will be stored
 *
 * \return    
 *    #POP3_STATUS_SUCCESS, if everything is successful
 *    Otherwise, one of the following error values
 *       
 *       #POP3_NOT_CONNECTED
 *       #POP3_RECEIVEMAIL_ERROR
 *
 * \sa        #pop3_getmaillist
 * \sa        #pop3_receivemail
 */
int  pop3_getmailboxstate(int *numberofmails, long *total_size);

/**
 * \brief  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.
 *
 *	<b>NOTE:</b>
 *		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
 *
 *	<b>NOTE:</b>
 *       User mail header name list should be set to retrieve user mail header values. 
 *  Otherwise, this function will ignore user mail header values.
 *
 * \param     mailnumber - Message number of mail to retrieve
 * \param     status - points to address location where status of pop3 function will be stored
 *
 * \return    NULL - if pop3_receivemail function failed. Otherwise, returns pointer to mail object
 *
 * \sa        #pop3_login
 * \sa        #pop3_logout
 * \sa        #pop3_getmaillist
 * \sa 		  #pop3_deletemail
 */
struct _mail *pop3_receivemail(int mailnumber, int *status);

/**
 * \brief      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.
 *
 * \param  status - points to address location where status of pop3 function will be stored
 *
 * \return NULL - if pop3_getmaillist failed. Otherwise, returns pointer to maillist object
 *
 * \sa        #pop3_login
 * \sa        #pop3_logout
 * \sa        #pop3_getmailboxstate
 * \sa 		  #pop3_deletemail
 */
struct _maillist *pop3_getmaillist(int *status);

/**
 * \brief   Terminates connection from pop3 server
 *
 *    This function terminates connection with pop3 server. if pop3 login operation was not performed, it returns error.
 *
 * \return     
 *    #POP3_STATUS_SUCCESS, if everything is successful
 *    Otherwise, one of the following error values
 *       
 *       #POP3_NOT_CONNECTED
 *       #POP3_RECEIVEMAIL_ERROR
 *
 * \sa  #pop3_login
 */
int  pop3_logout(void);

/**
 * \brief   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.
 *
 *  <b>NOTE:</b>
 *  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)
 *
 *  <b>NOTE:</b>
 *		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.
 *
 * \sa  #pop3_login, #pop3_session
 */
void pop3_registerauthcallback(int (*funpt)());

#endif