TABLE OF CONTENTS mailpro.library/--background-- mailpro.library/MP_AllocArchiverList mailpro.library/MP_AllocPacket mailpro.library/MP_CreateEntry mailpro.library/MP_CreateMessage mailpro.library/MP_CreatePacket mailpro.library/MP_CvtEndianLong mailpro.library/MP_CvtEndianWord mailpro.library/MP_DeleteEntry mailpro.library/MP_DeleteMessage mailpro.library/MP_FindEntry mailpro.library/MP_FreeArchiverList mailpro.library/MP_FreePacket mailpro.library/MP_IdentifyArchive mailpro.library/MP_InsertArchiver mailpro.library/MP_InsertEntry mailpro.library/MP_InsertMessage mailpro.library/MP_IsFile mailpro.library/MP_NextArchiver mailpro.library/MP_NextEntry mailpro.library/MP_NextMessage mailpro.library/MP_Pack mailpro.library/MP_PrevArchiver mailpro.library/MP_PrevEntry mailpro.library/MP_PrevMessage mailpro.library/MP_RemoveArchiver mailpro.library/MP_RootMessage mailpro.library/MP_RootPacket mailpro.library/MP_SavePacket mailpro.library/MP_ToArchiver mailpro.library/MP_ToEntry mailpro.library/MP_ToMessage mailpro.library/MP_UniqueName mailpro.library/MP_UnPack mailpro.library/--background-- mailpro.library/--background-- NAME MailPro -- Mail Professional library. FUNCTION This library was designed in helping programmers who creates fido- or amiganet software like, for example, mail tossers, mail processors etc. NOTES There are some structures which are used by this library. At main, you must know one rule: please avoid to creare these structures yourself because ones have private fields inside! Instead it please use library functions which can do it for you. Also please note that as for now the library supports only mail packets type 2 such us: 3D (FTS-0001), 4D (FSC-0048) and 5D (FSC-0045). mailpro.library/MP_IsFile mailpro.library/MP_IsFile NAME MP_IsFile - Tests file for needed mailtype. SYNOPSIS result = MP_IsFile(filename, pattern, mailtype) D0 A0 A1 D0 LONG MP_IsFile(STRPTR, STRPTR, ULONG) FUNCTION This routine tests is the file suitable for selected mailtype. It is possible to check it as by file name pattern as by internal recognization routines. You must specify at least one criteria for the test. If none criterias are set then function returns 0L. INPUTS filename -- a pointer to a file name (may contain path). pattern -- a pointer to the pattern string (like used in AmigaDOS patterns). This parameter is used for check the file name. There are some special values for this parameter, such us: MPISFP_SIMPLE_PACKET for pattern "????????.PKT" MPISFP_SIMPLE_PACKET_SUFFIX for pattern "#?.PKT" MPISFP_PACKED_PACKET for pattern "????????.(SU|MO|TU|WE|TH|FR|SA)?" MPISFP_PACKED_PACKET_SUFFIX for pattern "#?.(O|H|D|C)UT" MPISFP_FILE_LIST for pattern "#?.(F|H|D|C)LO" MPISFP_TIC_FILE for pattern "????????.TIC" MPISFP_RDM_FILE for pattern "????????.RDM" MPISFP_DONT_USE if you don't need to check the mailtype by the pattern. type -- a type of recognized files, currently: MPISFT_PKT non packed type 2 mail packet (3D, 4D or 5D); MPISFT_BINARY binary file; MPISFT_TEXT text file; MPISFT_DONT_USE if you don't need to check the mailtype by internal library's routines. RESULTS result -- 1L if test passed and 0L if don't. If any error occurs while checking then library error code will be returned. All internal error codes are negative values. NOTE Note that MP_IsFile does NOT recognize mailfile at 100% cases if you use MPISFT_PKT for mailtype parameter. It is because the mail files have not special ID fields inside. So be carefull! You may use own check routines if this function reports that test was passed. BUGS This routine uses DOS function ParsePatternNoCase(). From dos autodocs about this function: In V37 this call didn't always set IoErr() to something useful on an error. Fixed in V39. In V37, it didn't properly convert character-classes ([x-y]) to upper case. Fixed in V39 dos. Workaround: Use upper case characters for pattern string. SEE ALSO mail/mailpro.h mailpro.library/MP_Pack mailpro.library/MP_Pack NAME MP_Pack - Pack files into simple archive. SYNOPSIS error = MP_Pack(path, arcname, archiver, output) D0 A0 A1 A2 A3 LONG MP_Pack(STRPTR, STRPTR, struct ArchiverNode *, STRPTR) FUNCTION This routine packs all files from directory to simple file by selected archiver/packer. INPUTS path -- a directory in where files for packing are placed. arcname -- full path and name of archive in which files will be packed. Don't use relations to current or program directories here! archiver -- a pointer to struct ArchiverNode which describes the usage of archiver/packer. output -- a name of file in which archiver/packer will store report about its work. May be NULL if you don't need with it. RESULTS error -- 0L if all is okay. If any internal error occurs then library error code will be returned. All internal error codes are negative values. If any external error of archiver/packer occurs then this code will be returned as positive value. NOTE Note that most archivers/packers return error codes as standard shell error codes (5, 10, 20 etc). BUGS None SEE ALSO MP_UnPack(), MP_AllocArchiverList(), MP_FreeArchiverList(), MP_InsertArchiver(), MP_RemoveArchiver(), MP_NextArchiver(), MP_PrevArchiver(), MP_ToArchiver(), MP_IdentifyArchive() mailpro.library/MP_UnPack mailpro.library/MP_UnPack NAME MP_UnPack - Unpack archive into directory. SYNOPSIS error = MP_UnPack(arcname, path, archiverlist, output) D0 A0 A1 A2 A3 LONG MP_UnPack(STRPTR, STRPTR, struct List *, STRPTR) FUNCTION This routine unpacks the archive into directory. Routine does auto recognization for needed archiver/unpacker by tracing the list of nodes each one is struct ArchiverNode. INPUTS arcname -- full path and name of archive for unpacking. Don't use relations to current or program directories here! path -- a name of directory in which files will be unpacked. archiverlist -- a pointer to struct List which links descriptions of all available archivers/unpackers. output -- a name of file in which archiver/unpacker will store report about its work. May be NULL if you don't need with it. RESULTS error -- 0L if all is okay. If any internal error occurs then library error code will be returned. All internal error codes are negative values. If any external error of archiver/unpacker occurs then this code will be returned as positive value. NOTE Note that most archivers/unpackers return error codes as standard shell error codes (5, 10, 20 etc). BUGS None SEE ALSO MP_Pack(), MP_AllocArchiverList(), MP_FreeArchiverList(), MP_InsertArchiver(), MP_RemoveArchiver(), MP_NextArchiver(), MP_PrevArchiver(), MP_ToArchiver(), MP_IdentifyArchive() mailpro.library/MP_AllocPacket mailpro.library/MP_AllocPacket NAME MP_AllocPacket - Allocate and trace mail packet. SYNOPSIS packet = MP_AllocPacket(filename, error) D0 A0 A1 struct MailPacket *MP_AllocPacket(STRPTR, LONG *) FUNCTION This routine allocates memory for mail packet, loads and traces it. The routine makes database of the packet by creation of the lists and nodes. Any message of packet will be linked into messages' list which is in the struct MailPacket. Any entry of each message will be linked into entries' list which is in the struct MailMessage. INPUTS filename -- a name of file which is mail NON packed packet. error -- a pointer to LONG value where any error code will be placed. This parameter may be NULL. In this case error code will not be placed anywhere. RESULTS packet -- a pointer to struct MailPacket which contains database of mail packet. Or NULL if any error occurs. NOTE Always deallocate memory by MP_FreePacket() if you don't need to work with packet anymore. Also note that this routine does NOT check selected file for comtability to mail packet. You may do it yourself by MP_IsFile(). BUGS None SEE ALSO MP_FreePacket(), MP_CreatePacket(), MP_SavePacket() mailpro.library/MP_FreePacket mailpro.library/MP_FreePacket NAME MP_FreePacket - Free memory allocated for packet and database. SYNOPSIS MP_FreePacket(packet) A0 void MP_FreePacket(struct MailPacket *) FUNCTION This routine deallocates all memory which was allocalted by MP_AllocPacket() or by MP_CreatePacket() including memory of all mail messages and entries which are linked in this packet. INPUTS packet -- a pointer to a struct MailPacket which was created by MP_AllocPacket() or by MP_CreatePacket(). RESULTS NOTE Do not call this routine for any objects allocated in other way. Also note that after this call you must never use struct MailPacket which was freed. BUGS None SEE ALSO MP_AllocPacket(), MP_CreatePacket(), MP_SavePacket() mailpro.library/MP_NextMessage mailpro.library/MP_NextMessage NAME MP_NextMessage - Go to next packet message after indicated. SYNOPSIS message = MP_NextMessage(message) D0 A0 struct MailMessage *MP_NextMessage(struct MailMessage *) FUNCTION This routine returns pointer to the next packet message which is after selected. INPUTS message -- a pointer to the current struct MailMessage. RESULTS message -- a pointer to the next struct MailMessage. This routine returns NULL if current message is last message in the mail packet (there are no more messages after current one). This routine also returns NULL if you indicated the message which isn't linked into any mail packet. NOTE BUGS None SEE ALSO MP_PrevMessage(), MP_ToMessage(), MP_CreateMessage(), MP_InsertMessage(), MP_DeleteMessage() mailpro.library/MP_NextEntry mailpro.library/MP_NextEntry NAME MP_NextEntry - Go to next message entry after indicated. SYNOPSIS entry = MP_NextEntry(entry) D0 A0 struct MessageEntry *MP_NextEntry(struct MessageEntry *) FUNCTION This routine returns pointer to the next message entry which is after selected. INPUTS entry -- a pointer to the current struct MessageEntry. RESULTS entry -- a pointer to the next struct MessageEntry. This routine returns NULL if current entry is last entry in the packet message (there are no more entries after current one). This routine also returns NULL if you indicated the entry which isn't linked into any mail message. NOTE BUGS None SEE ALSO MP_PrevEntry(), MP_ToEntry(), MP_FindEntry(), MP_CreateEntry(), MP_InsertEntry(), MP_DeleteEntry() mailpro.library/MP_ToMessage mailpro.library/MP_ToMessage NAME MP_ToMessage - Go to packet message by number of one. SYNOPSIS message = MP_ToMessage(packet, number) D0 A0 D0 struct MailMessage *MP_ToMessage(struct MailPacket *, ULONG) FUNCTION This routine returns pointer to the packet message by the number of one. INPUTS packet -- a pointer to struct MailPacket. number -- a number of message in the packet (0, 1 etc). RESULTS message -- a pointer to struct MailMessage. This routine returns NULL if message with selected number is absent in the mail packet. NOTE BUGS None SEE ALSO MP_NextMessage(), MP_PrevMessage(), MP_CreateMessage(), MP_InsertMessage(), MP_DeleteMessage() mailpro.library/MP_ToEntry mailpro.library/MP_ToEntry NAME MP_ToEntry - Go to message entry by number of one. SYNOPSIS entry = MP_ToEntry(message, number) D0 A0 D0 struct MessageEntry *MP_NextEntry(struct MailMessage *, ULONG) FUNCTION This routine returns pointer to the message entry by the number of one. INPUTS message -- a pointer to struct MailMessage. number -- a number of entry in the mesage (0, 1 etc). RESULTS entry -- a pointer to struct MessageEntry. This routine returns NULL if entry with selected number is absent in the message. NOTE BUGS None SEE ALSO MP_NextEntry(), MP_PrevEntry(), MP_FindEntry(), MP_CreateEntry(), MP_InsertEntry(), MP_DeleteEntry() mailpro.library/MP_FindEntry mailpro.library/MP_FindEntry NAME MP_FindEntry - Search selected entry in the message. SYNOPSIS entry = MP_FindEntry(message, entry, id) D0 A0 A1 D0 struct MessageEntry *MP_FindEntry(struct MailMessage *, struct MessageEntry *, ULONG) FUNCTION This routine search message entry with selected identifier. If you need to find the first entry with specifed identifier then set entry to NULL. If you set this pointer to any other entry then searching will be continued from the next entry after it (for find multiple occurences). INPUTS message -- a pointer to struct MailMessage which searching will be done in. entry -- a pointer to struct MessageEntry which searching will be done after. It may be NULL for start search from the beginning of message. id -- an identifier of entry which you need to find. As for now there are next identifiers: Main: MEID_DATE the date of message; MEID_FROM the name of sender of message; MEID_TO the name of receiver of message; MEID_SUBJ the subject of message; MEID_AREA the area which is message for; MEID_BODY the body (text) of message; Main kludges: MEID_KL_DOMAIN, MEID_KL_FRPT, MEID_KL_TOPT, MEID_KL_MSGID, MEID_KL_PID, MEID_KL_REPLY, MEID_KL_CHRS, MEID_KL_TID, MEID_KL_INTL, MEID_KL_PATH, MEID_KL_REALNAME, MEID_KL_GIF, MEID_KL_EID, MEID_KL_VIA I-net kludges: MEID_KL_XMAILER, MEID_KL_REPLYADDR, MEID_KL_INREPLYTO, MEID_KL_RFC_PATH, MEID_KL_RFC_REF Mime kludges: MEID_KL_MIMEVERSION, MEID_KL_CONTENTTYPE, MEID_KL_CONTENTTREN, MEID_KL_RFC_MIMEVER, MEID_KL_RFC_CONTYPE Special: MEID_ENTRY_CORRUPTED corrupted entry; MEID_ENTRY_EMPTY the empty entry; MEID_ENTRY_UNKNOWN unknown entry. RESULTS entry -- a pointer to struct MessageEntry. This routine returns NULL if entry with selected identifier was not found. NOTE BUGS None SEE ALSO MP_ToEntry(), MP_NextEntry(), MP_PrevEntry(), MP_CreateEntry(), MP_InsertEntry(), MP_DeleteEntry(), mail/mailpro.h mailpro.library/MP_AllocArchiverList mailpro.library/MP_AllocArchiverList NAME MP_AllocArchiverList - Allocale and initializate archivers' list. SYNOPSIS archiverlist = MP_AllocArchiverList() D0 struct List *MP_AllocArchiverList(void) FUNCTION This routine allocates memory for struct List, initializates it as new list and returns pointer to this structure. INPUTS RESULTS archiverlist -- a pointer to struct List. This list is used for link the nodes each one is struct ArchiverNode. This routine returns NULL if there isn't enough memory for allocate the struct List. NOTE In fact this routine does not special manipulations with struct List with exception of initialization of the list as new one. So you may allocate and initializate such list yourself if you have the real reason for it. BUGS None SEE ALSO MP_FreeArchiverList(), MP_InsertArchiver(), MP_ToArchiver(), MP_NextArchiver(), MP_PrevArchiver(), MP_IdentifyArchive() mailpro.library/MP_InsertArchiver mailpro.library/MP_InsertArchiver NAME MP_InsertArchiver - Create archiver descriptor and link it to archivers' list. SYNOPSIS archiver = MP_InsertArchiver(archiverlist, seq, pack, unpack) D0 A0 A1 A2 A3 struct ArchiverNode *MP_InsertArchiver(struct List *, STRPTR, STRPTR, STRPTR) FUNCTION This routine creates struct ArchiverNode, fills its fields and inserts this node to archiverlist. INPUTS archiverlist -- a pointer to struct List in which the node will be inserted. seq -- a pointer to the string which describes procedure of archive type recognization. This string may contain special tokens such us: OFFSET: Offset in bytes from beginning of file to start comparation from. It must be followed by any decimal (example: 25), hexadecimal (0x2e) or octal (04) number. If it isn't indicated then default value 0 will be used. At this moment the maximal depth of comparation is 256 bytes. CHRS: the characters for comparation (ex, -lh5-); BIN: the values for comparation (ex, 0x20 0x34 0x02). Any base (octal, decimal and hexadecimal) and its mixing are possible. pack -- a pointer to the string which describe comand for create (packing) archive. unpack -- a pointer to the string which describe comand for extract files (unpacking archive). RESULTS archiver -- a pointer to struct ArchiverNode which was inserted in list. This routine returns NULL if there isn't enough memory for allocate the struct ArchiverNode and for strings' buffers. NOTE You must indicate in string of seq parameter only one type of comparation: CHRS: or BIN:. Both ones in one string aren't supported. Also note that this routine copies all strings into private buffers so you may trash original strings after this call. EXAMPLE MP_InsertArchiver(archiverlist, "OFFSET:2 CHRS:-lh5-", "C:lha a", "C:lha e"); BUGS None SEE ALSO MP_RemoveArchiver(), MP_NextArchiver(), MP_PrevArchiver(), MP_ToArchiver(), MP_FreeArchiverList() mailpro.library/MP_RemoveArchiver mailpro.library/MP_RemoveArchiver NAME MP_RemoveArchiver - Unlink archiver descriptor from archivers' list and deallocate it. SYNOPSIS MP_RemoveArchiver(archiver) A0 void MP_RemoveArchiver(struct ArchiverNode *) FUNCTION This routine removes archiver descriptor from archivers' list AND deallocates memory which was allocated for struct ArchiverNode and for strings' private buffers. INPUTS archiver -- a pointer to struct ArchiverNode which will be removed and deallocated. RESULTS NOTE BUGS None SEE ALSO MP_InsertArchiver(), MP_NextArchiver(), MP_PrevArchiver(), MP_ToArchiver(), MP_FreeArchiverList() mailpro.library/MP_FreeArchiverList mailpro.library/MP_FreeArchiverList NAME MP_FreeArchiverList - Deallocate all archivers' descriptors and archivers' list. SYNOPSIS MP_FreeArchiverList(archiverlist) A0 void MP_FreeArchiverList(struct List *) FUNCTION This routine removes all archivers' descriptors from archivers' list AND deallocates memory which was allocated for all struct ArchiverNode, for all private buffers and for the list. INPUTS archiverlist -- a pointer to struct List which links archivers' descriptors. RESULTS NOTE BUGS None SEE ALSO MP_AllocArchiverList(), MP_InsertArchiver(), MP_RemoveArchiver() mailpro.library/MP_NextArchiver mailpro.library/MP_NextArchiver NAME MP_NextArchiver - Go to next archiver descriptor after indicated. SYNOPSIS archiver = MP_NextArchiver(archiver) D0 A0 struct ArchiverNode *MP_NextArchiver(struct ArchiverNode *) FUNCTION This routine returns pointer to the next archiver descriptor which is after selected. INPUTS archiver -- a pointer to the current struct ArchiverNode. RESULTS archiver -- a pointer to the next struct ArchiverNode. This routine returns NULL if current archiver descriptor is last descriptor in the list (there are no more descriptors after current one). NOTE BUGS None SEE ALSO MP_PrevArchiver(), MP_ToArchiver(), MP_InsertArchiver(), MP_RemoveArchiver() mailpro.library/MP_ToArchiver mailpro.library/MP_ToArchiver NAME MP_ToArchiver - Go to archiver descriptor by number of one. SYNOPSIS archiver = MP_ToArchiver(archiverlist, number) D0 A0 D0 struct ArchiverNode *MP_ToArchiver(struct List *, ULONG) FUNCTION This routine returns pointer to the archiver descriptor in the list by the number of one. INPUTS archiverlist -- a pointer to struct List which links all archivers' descriptors. number -- a number of descriptor in the list (0, 1 etc). RESULTS archiver -- a pointer to struct ArchiverNode. This routine returns NULL if archive descriptor with selected number is absent in the list. NOTE BUGS None SEE ALSO MP_NextArchiver(), MP_PrevArchiver(), MP_InsertArchiver(), MP_RemoveArchiver() mailpro.library/MP_IdentifyArchive mailpro.library/MP_IdentifyArchive NAME MP_IdentifyArchive - Examine archive file and find needed archiver. SYNOPSIS archiver = MP_IdentifyArchive(arcname, archiverlist, error) D0 A0 A1 A2 struct ArchiverNode *MP_IdentifyArchive(STRPTR, struct List *, LONG *) FUNCTION This routine examine archive file and trace list of archivers' descriptors for search first suitable archiver descriptor. INPUTS arcname -- a pointer to the name of archive file archiverlist -- a pointer to struct List which links all archivers' descriptors. error -- a pointer to LONG value where any error code will be placed. This parameter may be NULL. In this case error code will not be placed anywhere. RESULTS archiver -- a pointer to struct ArchiverNode which is descriptor of suitable archiver. This routine returns NULL if suitable archive descriptor was not found or if any error was occured. In second case you may check error parameter for error code. NOTE BUGS None SEE ALSO MP_InsertArchiver() mailpro.library/MP_CvtEndianWord mailpro.library/MP_CvtEndianWord NAME MP_CvtEndianWord - Convert UWORD value between two formats. SYNOPSIS number = MP_CvtEndianWord(number) D0 D0 UWORD MP_CvtEndianWord(UWORD) FUNCTION This routine converts input UWORD value between Big-Endian and Little-Endian formats and vice versa. In fact 68K processors use Big-Endian format (highest byte in beginning). But most fields of mail packets are stored in Little-Endian format. INPUTS number -- a value in one format. RESULTS number -- a value in other format. NOTE BUGS None SEE ALSO MP_CvtEndianLong() mailpro.library/MP_CvtEndianLong mailpro.library/MP_CvtEndianLong NAME MP_CvtEndianLong - Convert ULONG value between two formats. SYNOPSIS number = MP_CvtEndianWord(number) D0 D0 ULONG MP_CvtEndianWord(ULONG) FUNCTION This routine converts input ULONG value between Big-Endian and Little-Endian formats and vice versa. In fact 68K processors use Big-Endian format (highest byte in beginning). But most fields of mail packets are stored in Little-Endian format. INPUTS number -- a value in one format. RESULTS number -- a value in other format. NOTE BUGS None SEE ALSO MP_CvtEndianWord() mailpro.library/MP_PrevMessage mailpro.library/MP_PrevMessage NAME MP_PrevMessage - Go to previous packet message before indicated. SYNOPSIS message = MP_PrevMessage(message) D0 A0 struct MailMessage *MP_PrevMessage(struct MailMessage *) FUNCTION This routine returns pointer to the previous packet message which is before selected. INPUTS message -- a pointer to the current struct MailMessage. RESULTS message -- a pointer to the previous struct MailMessage. This routine returns NULL if current message is first message in the mail packet (there are no messages before current one). NOTE BUGS None SEE ALSO MP_NextMessage(), MP_ToMessage(), MP_CreateMessage(), MP_InsertMessage(), MP_DeleteMessage() mailpro.library/MP_PrevEntry mailpro.library/MP_PrevEntry NAME MP_PrevEntry - Go to previous message entry before indicated. SYNOPSIS entry = MP_PrevEntry(entry) D0 A0 struct MessageEntry *MP_PrevEntry(struct MessageEntry *) FUNCTION This routine returns pointer to the previous message entry which is before selected. INPUTS entry -- a pointer to the current struct MessageEntry. RESULTS entry -- a pointer to the previous struct MessageEntry. This routine returns NULL if current entry is first entry in the packet message (there are no entries before current one). NOTE BUGS None SEE ALSO MP_NextEntry(), MP_ToEntry(), MP_FindEntry(), MP_CreateEntry(), MP_InsertEntry(), MP_DeleteEntry() mailpro.library/MP_PrevArchiver mailpro.library/MP_PrevArchiver NAME MP_PrevArchiver - Go to previous archiver descriptor before indicated. SYNOPSIS archiver = MP_PrevArchiver(archiver) D0 A0 struct ArchiverNode *MP_PrevArchiver(struct ArchiverNode *) FUNCTION This routine returns pointer to the previous archiver descriptor which is before selected. INPUTS archiver -- a pointer to the current struct ArchiverNode. RESULTS archiver -- a pointer to the previous struct ArchiverNode. This routine returns NULL if current archiver descriptor is first descriptor in the list (there are no descriptors before current one). NOTE BUGS None SEE ALSO MP_NextArchiver(), MP_ToArchiver(), MP_InsertArchiver(), MP_RemoveArchiver() mailpro.library/MP_CreateEntry mailpro.library/MP_CreateEntry NAME MP_CreateEntry - Create new message entry. SYNOPSIS entry = MP_CreateEntry(contents, size) D0 A0 D0 struct MessageEntry *MP_CreateEntry(STRPTR, ULONG) FUNCTION This routine allocates memory needed for struct MessageEntry and for private buffer, copies entry contents into this buffer and returns pointer to created entry. INPUTS contents -- a pointer to buffer where entry contents is placed. size -- a number of bytes which is lenght of entry contents. RESULTS entry -- a pointer to the new struct MessageEntry. This routine returns NULL if there isn't enough memory for creation. NOTE This routine copies entry contents into private buffer so you may trash original buffer after this call. Also please note that you must call MP_DeleteEntry() for this entry if you don't need with it anymore. Nevertheless if you link this entry in any mail message by MP_InsertEntry() then you may free all memory allocated for this entry by calling MP_DeleteMessage() without call MP_DeleteEntry(). It is important! BUGS None SEE ALSO MP_InsertEntry(), MP_DeleteEntry() mailpro.library/MP_CreateMessage mailpro.library/MP_CreateMessage NAME MP_CreateMessage - Create new mail message. SYNOPSIS message = MP_CreateMessage(header) D0 A0 struct MailMessage *MP_CreateMessage(struct MessageHeader *) FUNCTION This routine allocates memory needed for struct MailMessage and for private buffer, copies message header into this buffer and returns pointer to created message. INPUTS header -- a pointer to buffer where message header is placed. RESULTS message -- a pointer to the new struct MailMessage. This routine returns NULL if there isn't enough memory for creation. NOTE This routine copies message header into private buffer so you may trash original header buffer after this call. Also please note that you must call MP_DeleteMessage() for this message if you don't need with it anymore. Nevertheless if you link this message in any mail packet by MP_InsertMessage() then you may free all memory allocated for this message by calling MP_FreePacket() without call MP_DeleteMessage(). It is important! BUGS None SEE ALSO MP_InsertMessage(), MP_DeleteMessage() mailpro.library/MP_CreatePacket mailpro.library/MP_CreatePacket NAME MP_CreatePacket - Create new mail packet. SYNOPSIS packet = MP_CreatePacket(header) D0 A0 struct MailPacket *MP_CreatePacket(struct PacketHeader *) FUNCTION This routine allocates memory needed for struct MailPacket and for private buffer, copies packet header into this buffer and returns pointer to created packet. INPUTS header -- a pointer to buffer where packet header is placed. RESULTS packet -- a pointer to the new struct MailPacket. This routine returns NULL if there isn't enough memory for creation. NOTE This routine copies packet header into private buffer so you may trash original header buffer after this call. Also please note that you must call MP_FreePacket() for this packet if you don't need with it anymore. BUGS None SEE ALSO MP_AllocPacket(), MP_FreePacket() mailpro.library/MP_DeleteEntry mailpro.library/MP_DeleteEntry NAME MP_DeleteEntry - Delete message entry. SYNOPSIS MP_DeleteEntry(entry) A0 void MP_DeleteEntry(struct MessageEntry *) FUNCTION This routine deallocates memory which was allocated for entry and for private buffer if it was used. INPUTS entry -- a pointer to struct MessageEntry which will be deleted. RESULTS NOTE The routine also checks is indicated entry linked into any mail message. If does then the routine also unlinks entry from this root message and modifies some fields of struct MailMessage (such us mm_Size, mm_NumEntries and mm_Status). Moreover if root message is linked in any mail packet then the routine also modifies field mp_Size of root struct MailPacket. Please don't use entry pointer after this call anymore! BUGS None SEE ALSO MP_CreateEntry(), MP_InsertEntry() mailpro.library/MP_DeleteMessage mailpro.library/MP_DeleteMessage NAME MP_DeleteMessage - Delete mail message. SYNOPSIS MP_DeleteMessage(message) A0 void MP_DeleteMessage(struct MailMessage *) FUNCTION This routine deallocates memory which was allocated for message and for private buffer if it was used. The routine frees ALSO memory of all message entries which are linked in this message. INPUTS message -- a pointer to struct MailMessage which will be deleted. RESULTS NOTE Please note that this routine frees ALSO memory of all message entries which are linked in this message and you must NOT call MP_DeleteEntry() for such entries after this call. The routine also checks is indicated message linked into any mail packet. If does then the routine also unlinks message from this root packet and modifies some fields of struct MailPacket (such us mp_Size, mp_NumMess and mp_Status). Please don't use message pointer after this call anymore! BUGS None SEE ALSO MP_CreateMessage(), MP_InsertMessage() mailpro.library/MP_InsertEntry mailpro.library/MP_InsertEntry NAME MP_InsertEntry - Insert entry into mail message. SYNOPSIS MP_InsertEntry(entry, message, number) A0 A1 D0 void MP_InsertEntry(struct MessageEntry *, struct MailMessage *, ULONG) FUNCTION This routine links indicated entry to mail message in position selected by number. This routine also modifies some fields of struct MailMessage (such us mm_Size, mm_NumEntries and mm_Status). Moreover if the message is linked in any mail packet then the routine also modifies field mp_Size of root struct MailPacket. INPUTS entry -- a pointer to struct MessageEntry which will be inserted. message -- a pointer to struct MailMessage which entry will be inserted in. number -- a number of position for entry in the message (0, 1 etc). RESULTS NOTE If number is above of number of last message entry then the routine links entry at tail of message. Also note that you must NOT insert entries which are already linked in any messages. If you try to do it then routine doesn't link such entry twice. It is important! If you need to insert some entry which is already linked then you must before create copy of this entry by MP_CreateEntry(). BUGS None SEE ALSO MP_CreateEntry(), MP_DeleteEntry() mailpro.library/MP_InsertMessage mailpro.library/MP_InsertMessage NAME MP_InsertMessage - Insert message into mail packet. SYNOPSIS MP_InsertMessage(message, packet, number) A0 A1 D0 void MP_InsertMessage(struct MailMessage *, struct MailPacket *, ULONG) FUNCTION This routine links indicated message to mail packet in position selected by number. This routine also modifies some fields of struct MailPacket (such us mp_Size, mp_NumMess and mp_Status). INPUTS message -- a pointer to struct MailMessage which will be inserted. packet -- a pointer to struct MailPacket which message will be inserted in. number -- a number of position for message in the packet (0, 1 etc). RESULTS NOTE If number is above of number of last message in packet then the routine links message at tail of packet. Also note that you must NOT insert messages which are already linked in any packets. If you try to do it then routine doesn't link such message twice. It is important! If you need to insert some message which is already linked then you must before create copy of this message and all its entries by MP_CreateMessage(), MP_CreateEntry() and MP_InsertEntry(). BUGS None SEE ALSO MP_CreateMessage(), MP_DeleteMessage(), MP_CreateEntry(), MP_InsertEntry() mailpro.library/MP_RootMessage mailpro.library/MP_RootMessage NAME MP_RootMessage - Search for the root mail message of entry. SYNOPSIS message = MP_RootMessage(entry) D0 A0 struct MailMessage *MP_RootMessage(struct MessageEntry *) FUNCTION This routine examines message entry and try to find root message for this entry if entry is linked in any message. INPUTS entry -- a pointer to struct MessageEntry. RESULTS message -- a pointer to struct MailMessage which the entry is linked to. This routine returns NULL if the indicated entry is not linked to any mail message. NOTE The usage of this routine is only one valid way to search root message pointer due the size of most structures may be changed in next versions of library. And this routine also may help you to determine has entry been linked to any mail message or don't. BUGS None SEE ALSO MP_InsertEntry() mailpro.library/MP_RootPacket mailpro.library/MP_RootPacket NAME MP_RootPacket - Search for the root mail packet of message. SYNOPSIS packet = MP_RootPacket(message) D0 A0 struct MailPacket *MP_RootPacket(struct MailMessage *) FUNCTION This routine examines mail message and try to find root packet for this message if message is linked in any packet. INPUTS message -- a pointer to struct MailMessage. RESULTS packet -- a pointer to struct MailPacket which the message is linked to. This routine returns NULL if the indicated mail message is not linked to any mail packet. NOTE The usage of this routine is only one valid way to search root packet pointer due the size of most structures may be changed in next versions of library. And this routine also may help you to determine has message been linked to any mail packet or don't. BUGS None SEE ALSO MP_InsertMessage() mailpro.library/MP_UniqueName mailpro.library/MP_UniqueName NAME MP_UniqueName - Generate unique file name. SYNOPSIS string = MP_UniqueName(buffer, extension) D0 A0 A1 STRPTR MP_UniqueName(STRPTR, STRPTR) FUNCTION This routine makes unique file name with 8 bytes lenght and adds extension to it. INPUTS buffer -- a pointer to buffer where unique name will be placed. The size of this buffer must be at least lenght of extension plus 8 bytes for file name plus 2 bytes for the dot and for NULL terminator. extension -- a pointer to extension of name. May be NULL if you don't need to use it. Don't use dot before extension because the routine adds it itself. RESULTS string -- a pointer to the buffer. NOTE This routine does not check buffer size overflow so you must pass buffer with enough space. BUGS None SEE ALSO mailpro.library/MP_SavePacket mailpro.library/MP_SavePacket NAME MP_SavePacket - Save whole packet into simple file. SYNOPSIS error = MP_SavePacket(packet, filename) D0 A0 A1 LONG MP_SavePacket(struct MailPacket *, STRPTR) FUNCTION This routine saves whole mail packet to simple file. INPUTS packet -- a pointer to struct MailPacket which will be saved. filename -- a name of file in which packet will be saved. It may contain the path. If no path is specified then the path related to current or program directory will be used. If you specify NULL here then packet name from field mp_Name will be used. If this field hasn't the name then new name will be generated by MP_UniqueName() and used. RESULTS error -- 0L if all is okay. If any internal error occurs then library error code will be returned. All internal error codes are negative values. NOTE This routine skips while saving all corrupted or empty messages and also skips corrupted entries. If any message has only corrupted entries then such message will be skiped too. Nevertheless this routine may produce the file which contains empty mail packet without mail messages due it is possible at FCS standard. BUGS None SEE ALSO MP_AllocPacket(), MP_FreePacket(), MP_CreatePacket()