PurePOP3 library

Overview

POP3 functions for Purebasic.

This library is BETA.

Features :

- count messages at POP3 server
- get message text
- get message attachments
- and more

Error codes :

#PurePOP3_FileError = -1
#PurePOP3_NoConnection = -2
#PurePOP3_BadResponse = - 3
#PurePOP3_MemoryAllocationProblem = -4
#PurePOP3_AuthenticationFailed = -5
#PurePOP3_ServerTimeOut = -6

Functions

PurePOP3_SkipInitNetwork(SkipInit.l)

Skip InitNetwork() call.

By default, the library will call InitNetwork().
Note that InitNetwork() must only be called once. Use this function if you call InitNetwork() in your program to avoid the library calling it for the second time.

PurePOP3_SkipInitNetwork() must be called before any other function of this library.

PurePOP3_OpenPOP3Connection(pop3server.s, POP3Port.l, POP3UserName.s, POP3UserPassword.s)

Open connection to POP3 server.

Must be called before any other library function.

Returns #PurePOP3_Ok if success (else is error code).

PurePOP3_ClosePOP3Connection()

Close the POP3 connection.

Returns #PurePOP3_Ok if success (else is error code).

PurePOP3_GetLastServerMessage()

Get last server message (usefull after #PurePOP3_BadResponse).

PurePOP3_CountMessages()

Returns number of e-mails at POP3 server.

Returned values :
- >= 0 : number of e-mails
- < 0 : error code

PurePOP3_GetMessagesTotalSize()

Returns e-mails total size (in bytes) at POP3 server.

Returned values :
- >= 0 : e-mails total size
- < 0 : error code

PurePOP3_GetMessageSize(MessageNumber.l)

Returns e-mail size (in bytes) at POP3 server.

Returned values :
- >= 0 : e-mail size
- < 0 : error code

PurePOP3_DeleteMessage(MessageNumber.l)

Delete message at POP3 server.

Returns #PurePOP3_Ok if success (else is error code).

PurePOP3_Noop()

Does nothing ! It resets the server time-out.

Returns #PurePOP3_Ok if success (else is error code).

PurePOP3_Reset()

Reset message transactions.

Returns #PurePOP3_Ok if success (else is error code).

PurePOP3_RetrieveMessage(MessageNumber.l, [FileName.s])

Retrieve message from POP3 server.

If FileName is specified, the retrieved data is saved to the file (all the data : the header, the messages and all the attachements).

Returned values :
- >= 0 : bytes received if success
- < 0 : error code

PurePOP3_GetMessageInfo()

Get information about retrieved message.

Must be used after PurePOP3_RetrieveMessage().

Returned values :
- String like 'Delivery-date:xxx<9>Subject:xxx<9>From:xxx<9>Attachements:xxx<9>Length:xxx'
  where <9> is TAB (ASCII code 9)
- Empty string : error

PurePOP3_HeaderFindFirst()

Examine message header (gets the first line)
Use PurePOP3_HeaderFindNext() for the next lines.

Returned value :
- header first line
- empty string if error

PurePOP3_HeaderFindNext()

Examine message header (get next lines).
Initialize with PurePOP3_HeaderFindFirst().

Returned value :
- header line
- empty string if no more lines in header (examine complete)

PurePOP3_GetMessageTextInMemory([HTML.l])

Get text from retrieved message.
If HTML is #True, the retrieved text is "text/html" (default is "text/plain")

Must be used after PurePOP3_RetrieveMessage().

Returned values :
- > 0 : memory pointer to message text [ASCIIZ]
- 0 : error

The programmer has to free the memory when the task is done.

PurePOP3_ListAttachementsForMessage()

List attachements for retrieved message.

Must be used after PurePOP3_RetrieveMessage().

Returned values :
- String like 'Attachment1<9>Attachment2<9>..<9>AttachmentX'
  where <9> is TAB (ASCII code 9)
- Empty string : error

PurePOP3_SaveAttachementToFile(AttachementNumber.l, Directory.s)

Save attachement to specified directory.

Must be used after PurePOP3_RetrieveMessage().

If Directory = "", attachment is saved to current directory.

Returned values :
- > 0 : file length if success
- 0 : error

PurePOP3_SaveAttachementsToFile(Directory.s)

Save all attachements to specified directory.

Must be used after PurePOP3_RetrieveMessage().

If Directory = "", attachments are saved to current directory.

Returned values :
- > 0 : success
- 0 : error

PurePOP3_CountAttachedFiles()

Count the attached files.

Must be used after PurePOP3_RetrieveMessage().

PurePOP3_IsMessageHTML()

Check if there is an HTML version of the message ("text/html").

Must be used after PurePOP3_RetrieveMessage().

PurePOP3_GetMessageBufferAddress()

Get message buffer address.

Must be used after PurePOP3_RetrieveMessage().

Returned values :
- Not #Null : message buffer address
- #Null : buffer not allocated

PurePOP3_SetRetrieveCallback(*ProcedureAddress)

Set the progression callback address for PurePOP3_RetrieveMessage().
The callback is called in realtime during message retrieval.
Usefull to indicate the progress when a big file is retrieved.

Procedure MyCallback(Progression.f)
	; Progression : progression percentage)
EndProcedure

PurePOP3_Trace(OnOff.l)

Set debug mode on/off (#True/#False).

Creates PurePOP3-DEBUG*.txt files to help debugging.

PurePOP3_SetTimeOut(TimeOut.l)

Set server time-out.

Default is 15 s, minimum = 1s.