Home

Sun Java System Messaging Server 6 2005Q1 MTA Developer`s

1. Chapter 5 Decoding Messages 9 A Simple Decoding Example Code Example 5 1 Decoding MIME Messages Continued static const char message From sue siroe com n Date 31 Mar 2003 09 32 47 0800 Xn Subject test message n Content type multipart mixed boundary BoundaryMarker n BoundaryMarker n Content type text plain charset us ascii n Content disposition inline n An This is aM test message Mn BoundaryMarkerNn Content type application postscript n Content disposition attachment filename a ps n Content transfer encoding base64 n LyFQUwOxMDAgMTAwIG1vdmVObyAzMDAgMzAwIGxpbmVObyBzdHJva2UKc2hv 3Bh n Z2UK n BoundaryMarker n static mta_decode_read_t decode_read static mta_decode_inspect_t decode_inspect typedef struct const char cur_position const char end_position position_t main position_t pos Initialize the MTA SDK kf if ires mtaInit 0 mtaLog mtaInit returned d sWn ires mtaStrError ires 0 return 1 For a context to pass to mtaDecodeMessage we pass a pointer to the message data to be parsed The decode read routine uses this information when supplying data to mtaDecodeMessage See explanatory comment 2 ox pos cur position message pos end position message strlen message Invoke mtaDecodeMessage 1 Use decode read as
2. Syntax const char mtaAddressToChannel char channel size t channel len size t channel len max const char address size t address len int address type int item code Arguments Arguments Description channel A pointer to a buffer to receive the NULL terminated channel name To avoid possible truncation of the channel name this buffer must be at least CHANLENGTH 1 bytes long channel len An optional pointer to a size t to receive the length in bytes of the returned channel name This length does not include the NULL terminator that terminates the channel name channel len max The maximum size in bytes of the buffer pointed at by the channel argument address The address to rewrite The length of this address not including any NULL terminator should not exceed ALFA SIZE bytes If a value of 0 is passed for the address len argument then this string must be NULL terminated address len The length in bytes of the address string address This length does not include any NULL terminator If a value of 0 is passed for this argument the address string must be NULL terminated address type Indicates what type of address is being rewritten There are two types envelope or header In addition it can be either forward or reverse pointing See the description for a list of the possible values item code Reserved for future use Presently a value of 0 must be supplied for this argument 124 Messaging Server 6 2005Q1 MT
3. EOF When a line is read successfully mtabequeueLineNext returns a status of MTA OK Chapter 4 Dequeuing Messages 9 Processing the Message Queue 10 The lines returned by mtaDequeueLineNext might not be NULL terminated because the returned line pointer might reference a line in a read only memory mapped file 11 Once the message has been processed and all the disposition of all recipients set mtaDequeueMessageFinish is called This actually dequeues the message 12 When all message processing is complete process message exits It is called again for each additional message to be processed Output from the Simple Dequeue Example HELO MAIL FROM lt sue siroe com gt RCPT TO lt dan siroe com gt DATA Received from siroe com by siroe com SunONE Messaging Server 6 0 id 01GP37SOPRWOA9KZFVGsiroe com Fri 21 Mar 2003 09 07 32 0800 PST Date Fri 21 Mar 2003 09 07 41 0800 PST From postmaster siroe com To root siroe com Subject mtasdk examplel c Message id lt 01GP37SOPRW2A9KZFV siroe com gt Content type TEXT PLAIN CHARSET US ASCII Content transfer encoding 7BIT Hello world QUIT Processing the Message Queue This section describes the steps undertaken by each execution thread created by mtaDequeueStart Each execution thread processes a subset of the channel s queued messages by repeatedly calling the caller supplied processing routine process message
4. Arguments Arguments Description ctxl Optional pointer to a caller supplied context or other data type This pointer will be passed as the ct x1 argument to the caller supplied routines process_message and process_done A value of NULL may be passed for this argument process_message The address of a caller supplied routine to process each message process_done Optional address of a caller supplied clean up routine A NULL value may be passed for this argument item_code An optional list of item codes See the description section that follow for a list of item codes The list must be terminated with an integer argument with value 0 Description The mtaDequeueStart routine initiates processing of messages queued to a specific channel By default the channel serviced will be determined from the PMDF CHANNEL environment variable However a channel name can be explicitly specified with the MTA CHANNEL item code All of the item codes their additional arguments and a description of each are included in the table that follows Additional Arguments Description const char channel Explicitly specify the name of the channel name to perform dequeue processing for This item code must be followed by two additional call arguments the name of the channel and the length in bytes of that channel name If a value of zero is passed for the length then the channel name must be NULL terminated size t channel len When this item code is
5. Examples of Using mtaSend Example 1 Output Date 04 Oct 1992 22 24 07 0700 PDT From jdoe sesta com Subject send simple c To root sesta com Message id 01GPKF10JIB89LV1WXGsesta com MIME version 1 0 Content type TEXT PLAIN CHARSET US ASCII Content transfer encoding 7BIT send simple c Send a simple message include lt string h gt include mtasdk h Example 2 Specifying an Initial Message Header The program shown in Code Example 7 2 illustrates the use of the MTA HDRMSG FILE and MTA HDR ADRS item codes to enqueue a message that has already been composed including the headers and stored in a file The input file is given in the Example 2 Input File The resulting message is shown in Example 2 Output When the entire message header and body is contained in a single file use the MTA HDRMSG FILE item code in place of the MTA HDR FILE and MTA MSG FILE item codes Code Example 7 2 Specify an Initial Message Header send header c Send a message with initial header include lt string h gt include mtasdk h Push an entry onto the item list define ITEM item adr item list index item code item item list index item address adr item list index item length adr strlen adr 0 item_list index item_status 0 item_list index item_smessage NULL main MTA item list t item list 3 int index 0 ITEM ITEM ITEM exit MTA HDR ADRS 0 MTA HDR
6. The privileges to be enabled must either be granted to the program using mtaSend for example the program may have been installed with privileges or the process running the program must have the requisite privileges The mtasend routine and the MTA do not provide these privileges mtaSendDispose For each call to mtaSend where MTA ADR STATUS is used there should be a subsequent call to mtaSendDi spose Syntax void mtaSendDispose mta item list t item list Chapter 7 Using Callable Send mtaSend 241 Compiling and Linking Programs Arguments Argument Description item list Pointer to an array with elements of type mta item list t This should be an array previously passed to mtaSend Description Each call to this routine disposes of virtual memory allocated by mtaSend for returning address status information requested with the MTA ADR STATUS item code Return Values None Example item list index4 item code MTA ADR STATUS item list index item_ code MTA ITEM END istat mtaSend item list mtaSendDispose item list Compiling and Linking Programs Programs that use mtaSena are linked using the same steps as the MTA SDK routines For details see Chapter 2 MTA SDK Programming Considerations Examples of Using mtaSend Several example programs written in C are provided in this section Example 1 Sending a Simple Message Example 2 Specifying an Initial Message Header
7. for i 0 i gt lenl i ptrtt tolower ctype ptrtt for i 0 gt len2 i ptrtt tolower csubtypet 6 char 0x01 ptr 0 H gt Chapter 5 Decoding Messages 101 A Simple Virus Scanner Example Code Example 5 2 Decoding MIME Messages Complex Example Continued Now see if the literal just built occurs in the list of bad MIME content types x return strstr options bad mime types buf 1 0 is bad file type See if the part has an associated file name whose file extension is in our list of bad file names such as vbs See explanatory comment 14 static int is bad file type our options t options mta opt t params const char param name char buf size t maxbuflen const char ptrl char fext BIGALFA_SIZE 2 ptr2 size t i len Sanity checks e if loptions options bft len params param name return 0 len 0 buf 0 0 if mtaOptionString params param name 0 buf amp len maxbuflen 1 llen buf 0 No file name parameter specified return 0 A file name parameter was specified Parse it to extract the file extension portion if any x ptrl strrchr buf if ptrl No file extension specified return 0 Now store the string created earlier in fext Note that we drop the from the extension pt
8. 0 NULL Text of the message body 2 lines This generates output line 6 Messaging Server 6 2005Q1 MTA Developer s Reference 44 A Simple Example of Enqueuing a Message Code Example 3 1 Enqueuing a Message Continued CHECK mtaEnqueueWriteLine ctx Hello 0 NULL This generates output line 7 CHECK mtaEnqueueWriteLine ctx World 0 NULL Enqueue the message CHECK mtaEnqueueFinish ctx 0 All done mtaDone void quit void fprintf stderr The MTA SDK returned the error code d n Ss mta errno mtaStrError mta errno 0 if ctx mtaEnqueueFinish ctx MTA ABORT 0 exit 1 Enqueuing a Message Example Output The example that follows shows the output generated by the enqueuing example Comment numbers correspond to the numbered comments in Code Example 3 1 45 Output Lines Received from siroe com by siroe com SunONE Messaging Server 6 0 id 01GP37SOPRWOA9KZFV siroe com Fri 21 Mar 2003 09 07 32 0800 PST Date Fri 21 Mar 2003 09 07 41 0800 PST From postmaster siroe com To root siroe com Subject enqueuing example c essage id lt 01GP37SOPRW2A9KZFV siroe com gt Content type TEXT PLAIN CHARSET US ASCII Content transfer encoding 7BIT Hello World Chapter 3 Enqueuing Messages Comment Number BON PD UC 1 o0 01 Transferring Messages into the MTA Transferring Messages into the MT
9. A Simple Virus Scanner Example Date Fri 11 Apr 2003 13 03 08 0700 From sue sesta com Subject test message To sue sesta com Message id lt 0HD7001033P1DA00 frodo siroe com gt Content type multipart mixed boundary Boundary ID XIIwKLBET2 DDbPzRI7yzQ Boundary ID XIIwKLBET2 DDbPzRI7yzQ Content type text plain charset us ascii Content disposition inline This is a test message Boundary ID XIIwKLBET2 DDbPzRI7yzQ Content type text plain charset us ascii Content language en Content disposition inline The content of this message part has been removed It contained a potentially harmful file named trojan horse vbs Boundary ID XIIwKLBET2 DDbPzRI7yzQ Chapter 5 Decoding Messages 109 A Simple Virus Scanner Example 110 Messaging Server 6 2005Q1 MTA Developer s Reference Chapter 6 MTA SDK Reference The Sun Java System Messaging Server MTA SDK consists of numerous routines used to facilitate the enqueuing and dequeuing of messages This reference chapter contains definitions of all of the SDK routines and has the following sections Summary of SDK Routines This section contains a collection of tables representing a logical grouping of the routines Each table lists the routines in that group e MTA SDK Routines The actual reference material is organized in alphabetical order by routine name Summary of SDK Routines This sections contains a series of ta
10. A working knowledge of the following material is essential to programmers writing software that will create electronic mail messages with the MTA SDK e Sun Java System Messaging Server e RFC 2822 the successor to RFCs 822 and 1123 Understanding this RFC is essential for programmers writing software that creates electronic mail messages with this SDK e RFCs 2045 2046 2047 and 2049 These RFCs are useful for programmers interested in creating MIME compliant messages How This Book Is Organized This manual describes two distinct interfaces Each interface has an introductory chapter and a reference chapter and corresponding appendixes The chapters are Description Provides an overview and description of general described in the table below Table 1 How This Book Is Organized Chapter Chapter 1 MTA SDK Concepts and Overview concepts of the MTA SDK Describes procedures and run time instructions Describes the process of submitting a message to the MTA for delivery Describes the process of dequeing messages Describes the process of decoding messages Contains definitions of the MTA SDK routines Describes the MTA Callable Send facility which is used to send mail messages from the local host Provides syntax and item codes for the mtaSend routine Describes the error status codes returned by the MTA SDK and mtaSend Chapter 2 MTA SDK Programming Considerations Chapter 3 Enqueuin
11. Output the command RCPT TO lt to adr gt for each recipient address ui See explanatory comment 6 while ires mtaDequeueRecipientNext dq amp to amp len 0 printf RCPT TO lt s gt n to See explanatory comment 7 mtaDequeueRecipientDisposition dg to len MTA DISP DELIVERED 0 If ires MTA EOF then we exited the loop normally otherwise there s been an error of some sort if ires MTA_EOF See explanatory comment 8 return ires Now output the message itself printf DATA n See explanatory comment 9 while ires mtaDequeueLineNext dq amp line amp len See explanatory comment 10 printf sWMn len line If ires MTA EOF then we exited normally otherwise there s been an error of some sort if ires MTA_EOF See explanatory comment 8 return ires Output the command to terminate this message printf n And dequeue the message See explanatory comment 11 58 Messaging Server 6 2005001 MTA Developer s Reference A Simple Dequeue Example Code Example 4 1 A Simple Dequeue Example Continued ires mtaDequeueMessageFinish dq 0 All done return ires as our result See explanatory comment 12 return ires Explanatory Text for Numbered Comments The numbered explanatory text that follows corresponds to the numbered
12. Symbols The following table describes the symbol conventions used in this book Meaning The 1 option is not required Preface 13 Table 3 Symbol Conventions Symbol Description Example I3 Contains optional command 1s 1 options Meaning The d option requires that you use either the y argument or the n argument Press the Control key while you press the A key Press the Control key release it and then press the subsequent keys From the File menu choose New From the New submenu choose Templates Represents the base installation directory for Messaging Server Symbol Conventions Continued Example d Control A Ctrl A N File gt New gt Templates Description Contains a set of choices for a required command option Joins simultaneous multiple keystrokes Joins consecutive multiple keystrokes Indicates menu item selection in a graphical user interface Conventions Used in This Book Table 3 Symbol Default Paths and File Names The following table describes the default paths and file names used in this book Default Paths and File Names Description The default value of the msg sor base installation is as follows Solaris systems opt SUNWmsgsr Linux systems opt sun messaging Table 4 Term msg sor base Command Line Prompts Command line prompts for example for a C Shell or for a Korn or Bourne sh
13. len Optional address of a size t to receive the length of the returned line A value of NULL may be passed for this argument Description After exhausting a message s list of envelope recipients by repeated calls to mtaDequeueRecipientNext begin reading the message s header and content with mtaDequeueLineNext Each call will return one line of the message with the first call returning the first line of the message the second call the second line and so on Once the message has been completely read the status code MTA_EOF will be returned The returned lines of the message will not be NULL terminated This is because the underlying message file is often mapped into memory When that is the case then the returned pointer is a pointer into that memory map Since the message files themselves do not contain NULL terminators and the file is mapped read only it is not possible for the SDK to add a NULL terminator to the end of the line without copying it first to a writable portion of memory The returned lines of the message will not have any line terminators such as a line feed or a carriage return It is up to the calling routine to supply whatever line terminators might be appropriate for example adding a carriage return line feed pair when transmitting the line over SMTP Itis possible to call ntabequeueLineNext with NULL values for both the 1ine and len call arguments But this is of limited use one example is when writin
14. that is bytes per block mtaBlockSize block limit byte limit bytes per block 126 Messaging Server 6 2005Q1 MTA Developer s Reference mtaChannelGetName Return Values In the event of a failure the routine returns the value zero and sets mta errno with an error status code This routine only fails when initialization of the MTA SDK fails The following table lists the error status codes set in mta errno when there is an error returned by mt aBlockSize Error Status Codes Description MTA FOPEN Unable to initialize the MTA SDK Unable to read one or more configuration files Issue the following command for further information imsimta test rewrite MTA NO Unable to initialize the MTA SDK Issue the following command for further information imsimta test rewrite Example The following code fragment displays the MTA block size setting printf BLOCK SIZE Suin mtaBlockSize mtaChannelGetName Determine the channel name for the currently running program Chapter 6 MTA SDK Reference 7 Syntax const char mtaChannelGetName char channel size_t channel len size t channel len max Arguments Arguments Description channel A pointer to a buffer to receive the NULL terminated channel name To avoid possible truncation of the channel name this buffer must be at least CHANLENGTH 1 bytes long channel len An optional pointer to a size t to receive the le
15. 8 Ifthe process message routine did not return the MTA ABORT status code then repeat this cycle starting at Step 2 9 Ifacaller supplied process done routine was passed to mtaDequeueStart it is called now for example process done amp ctx2 ctxl Through the process done routine the program can perform any cleanup necessary for the execution thread For example freeing up any private context and associated resources stored in the ctx2 call argument For a description of the process done routine see The process done Routine that follows as well as process done Routine on page 180 10 The thread exits For an example of how state context may be preserved within an execution thread and across calls to process message A Complex Dequeuing Example on page 63 That example also illustrates the use of the process done routine Chapter 4 Dequeuing Messages 61 The process done Routine The process done Routine To assist in cleaning up state information for a thread callers can provide a routine pointed to by the process done call argument of mtaDequeueStart The following code example shows the required syntax for a process done routine void process done void ctx2 void ctxl The following table lists the arguments required for a process done routine and gives a description of each Required Arguments Description GERZ The value of the last pointer sto
16. Example 3 Sending a Message to Multiple Recipients Example 4 Using an Input Procedure to Generate the Message Body The example routines shown in this section may be found in the examples mta sdk directory Messaging Server 6 2005Q1 MTA Developer s Reference 242 Examples of Using mtaSend Example 1 Sending a Simple Message The program shown in Code Example 7 1 demonstrates how to send a simple message to the root account The source code itself is used as the input source for the body of the message to be sent The From address associated with the message 243 is that of the process running the program Comments in the program example explain the sample output line they generate Code Example 7 1 Send a Simple Message send simple c Send a simple message include lt string h gt include mtasdk h Push an entry onto the item list define ITEM item adr item list index item code item item list index item address adr item list index item length adr strlen adr 0 item list index item status 0 item_list index item_smessage NULL main mta_item_list_t item_list 4 int index 0 ITEM MTA_TO root Becomes the To line in the output ITEM MTA SUBJECT send simple c ITEM MTA MSG FILE FILE Becomes the Subject line ITEM MTA END LIST 0 exit mtaSend item list Chapter7 Using Callable Send mtaSend
17. Intermediate Channel Example Code Example 4 3 Intermediate Channel Example Continued if my ctx 2 return rbuf rotl3 buf t my ctx 2 if rbuf gt buf free rbuf buf free rbuf process message Process a single message by re enqueuing but x with its message body converted to the rot13 A set The private my ctx 1 context is not used The private my ctx 2 context is used for a rot13 translation context See explanatory comment 5 static int process message void my ctx 2 void my ctx 1 mta dq t dq size_t len const char line to int in_header mta_ng_t nq Start a message enqueue ng NULL See explanatory comment 6 if mtaEnqueueStart amp nq env from env from len MTA DQ CONTEXT dq 0 goto defer Process the envelope recipient list See explanatory comment 7 while mtaDequeueRecipientNext dg amp to amp len 0 See explanatory comment 7 if mtaEnqueueTo ng to len MTA DQ CONTEXT dq MTA ENV TO 0 See explanatory comment 8 mtaDequeueRecipientDisposition dq to len DISP DELIVERED 0 See explanatory comment 9 goto defer if mta errno MTA EOF goto defer First get the message s header and write it unchanged to the new message being enqueued See explanatory comment 10 Chapter 4 Dequeuing Messages 75 Intermediate Channel Example Code Example 4
18. L3 nde bes Example ici oda der ang ia Threads and Enqueue Contexts u 4 Enqueuing 1260160160 Mail 2 Diequeuine Messages nit Threads and Dequeue Contexts ooommooooo mo Message Processing Threads String valued Call 1065 560 cee sue Item Codes and Item Lists cee ee eens Chapter 2 MTA SDK Programming Considerations Running Your Enqueue and Dequeue Programs Debugging Programs and Logging Diagnostics Required Privileges e Cors beasties oie e RIEF PSU a eae Compiling and Linking Programs ss OPN OUTS caucas doce be nr s sete aa Linking Instructions for Solaris Running Your Test 02 8 35 dias rmassi pas Preventing Mail Loops when Re enqueuing Mail Miscellaneous Programming Considerations Retrieving Error Codes coins Writing Output From a Channel Program Considerations for Persistent Programs Refreshing Stale Configuration Information Keeping the Log File Available For Update Chapter 3 Enqueuing Messages Basic Steps to Enqueue 09582068 7777 Originating Messages cree eere e Ye A Simple Example of Enqueuing a Message Enqueuing a Message Example Output Transferring Messages into the MTA Intermediate Processing Channels Delivery Processing Options Envelope fields Order Dependenc
19. Size t env id len This item code must be followed by two additional call arguments 1 The address of a pointer to receive the address of the NULL terminated envelope ID 2 The address of a size t to receive the length of that envelope ID A NULL value may be passed for the env id len argument Chapter 6 MTA SDK Reference 1 Description Retrieve the expand limit setting specified with mtaEnqueueStart The returned value will be a positive integer value When no expand limit has been set the returned value will be a large integer value for example 2 147 483 647 on 32 bit processors This item code must be followed by one additional argument the address of a size t to store the setting s value in Obtain the value if any specified for the MTA FRAGMENT BLOCKS setting when the message enqueue was initiated The returned value will be a positive integer value When no value was set the returned value will be a large integer value for example 2 147 483 647 on 32 bit processors This item code must be followed by one additional argument the address of a size t to store the setting s value in Obtain the value specified for the MTA FRAGMENT LINES setting when the message enqueue was initiated The returned value will be a positive integer value When no value was set the returned value will be a large integer value for example 2 147 483 647 on 32 bit processors This item code must be followed by one
20. Sun Java System Messaging Server 6 MTA Developer s Reference 200501 Sun Microsystems Inc 4150 Network Circle Santa Clara CA 95054 U S A Part No 819 0107 10 Copyright 2005 Sun Microsystems Inc 4150 Network Circle Santa Clara California 95054 U S A All rights reserved Sun Microsystems Inc has intellectual property rights relating to technology embodied in the product that is described in this document In particular and without limitation these intellectual property rights may include one or more of the U S patents listed at http www sun com patents and one or more additional patents or pending patent applications in the U S and in other countries THIS PRODUCT CONTAINS CONFIDENTIAL INFORMATION AND TRADE SECRETS OF SUN MICROSYSTEMS INC USE DISCLOSURE OR REPRODUCTION IS PROHIBITED WITHOUT THE PRIOR EXPRESS WRITTEN PERMISSION OF SUN MICROSYSTEMS INC US Government Rights Commercial software Government users are subject to the Sun Microsystems Inc standard license agreement and applicable provisions of the FAR and its supplements This distribution may include materials developed by third parties Parts of the product may be derived from Berkeley BSD systems licensed from the University of California UNIX is a registered trademark in the U S and in other countries exclusively licensed through X Open Company Ltd Sun Sun Microsystems the Sun logo Java Solaris JDK Java Naming and Directory Int
21. mtaDequeueLineNext mtaDequeueRewind mtaEnqueueCopyMessage mtaDequeueInfo mtaDequeueThreadld mtaDequeueMessageFinish Chapter 4 Dequeuing Messages 3 Calling Order Dependencies 84 Messaging Server 6 200501 MTA Developer s Reference Chapter 5 Decoding Messages The MTA has facilities for parsing and decoding single and multipart messages formatted using the MIME Internet messaging format Additionally these facilities can convert messages with other formats to MIME For example messages with BINHEX or UUENCODE data the RFC 1154 format and many other proprietary formats The mt aDecodeMessage routine provides access to these facilities parsing either a queued message or a message from an arbitrary source such as a disk file or a data stream This chapter discusses the following topics e Usage Modes for mtaDecodeMessage on page 85 The Input Source on page 87 The Inspection Routine on page 88 A Simple Decoding Example on page 89 e The Output Destination on page 93 e Decode Contexts on page 94 e A Simple Virus Scanner Example on page 95 Usage Modes for mtaDecodeMessage There are two usage modes for mt aDecodeMessage In the first mode messages are simply parsed any encoded content decoded and each resulting atomic message part presented to an inspection routine This mode of usage is primarily of use to channels which interface the MTA to non Internet
22. root ITEM MTA TO abuse sample com ITEM MTA CC postmaster sample com Now terminate the item list ITEM MTA END LIST 0 And send the message istat mtaSend item list Sends the message Display the address status messages provided that no error other than MTA HOST has occurred Messaging Server 6 2005021 MTA Developer s Reference 246 Examples of Using mtaSend Code Example 7 3 Sending a Message to Multiple Recipients Continued for 1 0 1 gt index 1 Display any returned status messages if item list i item smessage printf 8 s s n const char item list i item address item list i item status Failed Succeeded item list i item smessage Dispose of status messages mtaSendDispose item list exit istat Example 3 Output Succeeded root sample com Succeeded abuse sample com Succeeded postmaster sample com Example 4 Using an Input Procedure to Generate the Message Body The program shown in Code Example 7 4 uses an input procedure as the source for the body of a message to be sent In the program the input procedure msg_proc will read input until the runtime library routine fgets signals an EOF condition for example a control D has been input The address of the procedure msg proc is passed to mtaSend using a MTA MSG PROC item code The mtaSend routine repeatedly calls the 50 pro
23. 0 amp local NULL MTA ADDR LOCAL mtaAddressGetN adr ctx 0 amp domain NULL MTA ADDR DOMAIN strcpy buf local strcat buf 6 strcat buf domain Return Values Return Value Description 0 Normal successful completion MTA BADARGS One of the following conditions occurred 1 A NULL value for the adr content argument 2 Aninvalid address context 3 Aninvalid bitmask for elements MTA EOF The value supplied for the address index is equal to or greater than the number of addresses in the address list Example The following is a code fragment that parses and displays the individual addresses from a list of two addresses using mtaAddressGetN ires mtaAddressParse amp adr ctx amp adr count Judy Public lt judy public siroe com gt sue siroe com 0 0 for i 0 i gt adr count i mtaAddressGetN adr ctx i amp ptr NULL MTA ADDR LOCAL MTA ADDR DOMAIN printf Address d s n i ptr mtaA ddressParse Parse a list of comma separated RFC 822 addresses Chapter 6 MTA SDK Reference 1 Syntax int mtaAddressParse mta adr t adr ctx size t address count const char address list size t address list len int item code Arguments Argument Description adr ctx The address context created for the parsed list of addresses address count The number of addresses parsed address list A character string containing the list of comma separated RFC 822
24. 27 ptrO0 break ptrl char 0x01 ptrl options bft len ptrl options gt bad_file types Dispose of the mta opt t context See explanatory comment 17 ui mtaOptionFinish channel opts And return a success t return MTA OK error report Report an error condition when debugging is enabled static void error_report our_options_t options int ires const char func if options gt debug mtaLog s returned d s func func ires mtaStrError ires error exit Exit with an error status and error message El static void error_exit int 1268 const char msg mtaLog s s s msg msg msg mtaStrError ires exit 1 Chapter 5 Decoding Messages 5 A Simple Virus Scanner Example Example Option File This example lists the MIME media types and file extensions this program is to consider potentially harmful DEBUG 1 BAD MIME TYPES application vbscript BAD_FILE_TYPES bat com dll exe vb vbs Sample Input Message The example that follows is the text of a sample input message the program in Code Example 5 2 on page 96 is to process The second message part is a file attachment The attached file name is trojan_horse vbs Consequently when this message is processed by the channel it should remove the attachment as the file extension vbs is in the list of harmful file exte
25. 276 Messaging Server 6 2005Q1 MTA Developer s Reference Section T patches 16 support 16 stack size 229 state information management 22 stdout and other generic I O destinations 38 string call arguments 27 string size constants 27 support Solaris 16 T test programs steps for running manually 36 threads contexts 22 dequeue contexts 26 enqueuing messages 24 stack size 229 thread creation loop 80 time 131 to addresses 205 239 V version routines mtaVersionMajor 231 mtaVersionMinor 232 mtaVersionRevision 232 virus scanner example 95 W writing output use of stdout 38 mtaEnqueueStart 113 193 mtaEnqueueTo 113 200 mtaEnqueueWrite 113 206 mtaEnqueueWriteLine 113 209 error handling mtaErrno 113 211 mtaStrError 113 230 initialization mtaDone 113 183 mtalnit 113 211 212 list of 116 logging and diagnostic mtaDebug 133 mtaLog 215 mtaLogv 217 logging and diagnostics mtaDebug 114 mtaLog 114 mtaLogv 114 MIME decoding mtaDecodeMessage 114 135 mtaDecodeMessagelnfoInt 114 145 mtaDecodeMessagelnfoParams 114 147 mtaDecodeMessagelnfoString 114 149 mtaDecodeMessagePartCopy 114 151 mtaDecodeMessagePartDelete 114 152 miscellaneous mtaAccountingLogClose 114 117 mtaAddressToChannel 114 123 mtaBlockSize 114 126 mtaChannelGetName 114 127 mtaChannelToHost 114 129 mtaDateTime 114 131 mtaPostmasterAddress 114 227 mtaStackSize 114 229 mtaUniqueString 114 230 mtaVersionMajor 114 231 mtaVersionMino
26. The basic steps necessary to enqueue one or more messages to the MTA are 1 Initialize SDK resources and data structures with mtaInit 2 Foreach message to enqueue perform the following steps a Specify the message envelope with mtaEnqueuestart and mtaEnqueueTo b Specify the message header with mtaEnqueueWrite or mtaEnqueueWriteLine c Optionally if a message body is to be supplied terminate the message header and start the message body by writing a blank line to the message with mtaEnqueueWrite Or mtaEnqueueWriteLine d Optionally if a message body is to be supplied write the message body with mtaEnqueueWrite Or mtaEnqueueWriteLine e Submit the message with mtaEnqueueFinish 3 When you have completed enqueuing messages deallocate SDK resources and data structures with mtaDone In Step 2e mtaEnqueueFinish commits the message to disk As part of the enqueue process the MTA performs any access checks size checks format conversions address rewritings and other tasks called for by the site s MTA configuration After these steps are completed and the message has been successfully written to disk mtaEnqueueFinish returns Other MTA processes controlled by the MTA Job Controller then begin processing the new message so as to effect its delivery In fact these processes may begin handling the new message before mtaEnqueueFinish even returns As such mtaEngeueueFinish doesn
27. mtaDecodeMessage Each line passed to the output routine represents a complete line of the message to beoutput The output routine must add to the line any line terminators required by the output destination for example carriage return line feed pairs if transmitting over the SMTP protocol or line feed terminators if writing to a UNIX text file Supplying a value of zero for the output type call argument causes the output argument to be ignored In this case no output routine will be used Decode Context Queries When ntaDecodeMessage calls either a caller supplied inspection or output routine it passes to those routines a decode context Through various SDK routine calls this decode context may be queried to obtain information about the message part currently being processed The following table lists the informational message codes that can be obtained about a message part being processed and gives a description of each including the SDK routine used to obtain it Description The character set specified with the CHARSET parameter of the part s Content type header line If the part lacks a CHARSET specification then the value us ascii will be returned Obtain with mtaDecodeMessageInfoString Value of the Content disposition header line less any optional parameters Will be a zero length string if the part lacks a Content disposition header line Obtain with mtaDecodeMessageInfoString Parameter list to the Cont
28. on page 36 Messaging Server 6 2005Q1 MTA Developer s Reference 34 Running Your Test Programs Running in a Messaging Environment Perform the following tasks 1 Adda test channel to the bottom of the imta cnf file as illustrated in the following example required blank line x test x test daemon 2 Add rewrite rules to the top of the imta cnf file as illustrated in the following code fragment x test U x test x test daemon 3 To enable your test channel so that mail can be addressed recompile your configuration and restart the SMTP server using the instructions found in the following code example f imsimta cnbuild imsimta restart dispatcher 4 Create the job controller site text file The file should be owned by the Messaging Server and reside in the same directory as the job controller cnf file The following code example shows the lines you must add to the file CHANNEL x test master command file path In the above example file path is the full path to your executable program 5 Make sure your executable has permissions and ownership such that the Messaging Server can run it 6 Restart the Job Controller with the command found in the following code example imsimta restart job controller Chapter 2 MTA SDK Programming Considerations 5 Running Your Test Programs If the program performing enqueues is also a channel that will be dequeuing
29. returned as the routines return status Return Values In the event of an error mtaUniqueString will return NULL The error status code may be obtained by examining the value of mta errno Error Status Codes Description MTA BADARGS A value of NULL was supplied for the buf argument MTA STRTRUERR The buf buffer is too small Example This routine is used in Decoding MIME Messages Complex Example on page 96 mtaVersionMajor Obtain the major version number associated with the MTA SDK library Chapter 6 MTA SDK Reference 231 mtaVersionMinor Syntax int mtaVersionMajor void Arguments None Description Return the major version number associated with the MTA SDK library Return Values The SDK major version number Example printf MTA SDK Version d d d n mtaVersionMajor mtaVersionMinor mtaVersionRevision e e mtaVersionMinor Obtain the minor version number associated with the MTA SDK library Syntax int mtaVersionMinor void Arguments None Description Return the minor version number associated with the MTA SDK library Return Values The SDK minor version number Example printf MTA SDK Version d d d n mtaVersionMajor mtaVersionMinor mtaVersionRevision mtaVersionRevision Obtain the revision level associated with the MTA SDK library 232 Messaging Server 6 2005Q1 MTA Developer s Reference mtaVersionRevision Syntax in
30. s Sun reconna t les efforts de pionniers de Xerox pour la recherche et le d veloppement du concept des interfaces d utilisation visuelle ou graphique pour l industrie de l informatique Sun d tient une license non exclusive de Xerox sur l interface d utilisation graphique Xerox cette licence couvrant galement les licenci s de Sun qui mettent en place l interface d utilisation graphique OPEN LOOK et qui en outre se conforment aux licences crites de Sun Ce produit comprend du logiciel d velop par Computing Services Carnegie Mellon University http www cmu edu computing Les produits qui font l objet de ce manuel d entretien et les informations qu il contient sont regis par la legislation americaine en matiere de controle des exportations et peuvent etre soumis au droit d autres pays dans le domaine des exportations et importations Les utilisations finales ou utilisateurs finaux pour des armes nucleaires des missiles des armes biologiques et chimiques ou du nucleaire maritime directement ou indirectement sont strictement interdites Les exportations ou reexportations vers des pays sous embargo des Etats Unis ou vers des entites figurant sur les listes d exclusion d exportation americaines y compris mais de maniere non exclusive la liste de personnes qui font objet d un ordre de ne pas participer d une facon directe ou indirecte aux exportations des produits ou des services qui sont regi par la legislation americaine en matiere
31. there is no one to deliver the message to In the envelope there is no distinction between To Cc or Bcc addressees Additionally the list of addressees appearing in the message s header need not be the same as those appearing in the envelope This is the case with list oriented mail The address in the message s header is often the list s mail address whereas the addresses in the envelope are the those of the list s individual members By default when an address is added to a message with mtaEnqueueTo it is added as both an envelope recipient address as well as a To addressee in the message s To header line The address is therefore considered to be an active transport address as well as a header address This case corresponds to the MTA TO item code To instead mark an active transport address for addition to either a Cc or Bcc header line use the MTA CC or MTA_BCC item code Chapter 6 MTA SDK Reference 201 Addresses that only appear in the message s header are sometimes referred to as inactive addresses Such addresses added with mtaEnqueueTo may be noted as such with the MTA HDR TO MTA HDR CC and HDR 860 item codes They can also be manually added by constructing the To Cc or Bcc header lines with mtaEnqueueWrite Or mtaEnqueueWriteLine NOTE The MTA SDK will automatically generate multiple message copies when Bcc recipients exist for the message Specifically when a message has N e
32. with one pair per line mtaEnqueueWrite nq Date today n 0 From sue siroe com n 0 To bob siroe com n 0 Subject test n 0 NEU 0 NULL mtaEnqueueWriteLine Write a complete single line of message data to the message being submitted Syntax int mtaEnqueueWrite mta nq t nq ctx const char strl size t lenl const char str2 aads Zero or more string pointer length pairs can be supplied to this routine The list of pairs must be terminated by a NULL call argument Chapter 6 MTA SDK Reference 9 Description Pointer to an enqueue context created with mtaEnqueueStart Pointer to a string of text to write to the message The string must be NULL terminated if a value of zero is passed for 1 The length in bytes not including any NULL terminator of the string 5611 If a value of zero is passed for this argument then the string str1 must be NULL terminated Pointer to a second string of text to write to the message The string must be NULL terminated if a value of zero is passed for 1en2 If only supplying a single string then pass a NULL value for this argument Arguments Arguments nq ctx strl 111 str2 Description After a message s list of envelope recipient addresses has been supplied with mtaEnqueueTo the message itself must be supplied This can be done by repeatedly calling mtaEnqueueWriteLine First the message s header should be supplied
33. C pre processor macro The exceptional routines either return nothing that is always succeed or return a string pointer and signify an error with a return value of NULL Writing Output From a Channel Program The C runtime library stdout input output destination may be usurped by the SDK depending upon the context under which a channel program has been invoked As such programs that will operate as channels should use the mt aLog routine to write information to their log file Such programs should never write output directly to stdout or stderr or other generic I O destinations such as Pascal s output or FORTRAN s default output logical unit There s no telling where such output might go it might go to the Job Controller s log file it might even go down a network pipe to a remote client or server NOTE The channel log file is a different file than the MTA log file The mtaLog and mtaAccountingLogClose are unrelated routines Considerations for Persistent Programs There are two main problems to consider when creating programs that persist over long periods of time for weeks or months Refreshing Stale Configuration Information 38 Messaging Server 6 2005001 MTA Developer s Reference Miscellaneous Programming Considerations e Keeping the Log File Available For Update Refreshing Stale Configuration Information Some programs once started run indefinitely for weeks or months An example of this kind o
34. Calling Order Dependencies coi obs tha stad owed ET UR Rr aa ER Eel edad as Giada 82 Chapter 5 Decoding Messages seseeeeee en nn nnn 85 Usage Modes for miaDecodeNlessagel ee REUS ed 85 The MPU OUE ei ers Dusche dass doe cx ened aoe aah ater UR paene quia atte ME HE apes 87 65 20 A pec bd d Op ante I P Aue 87 Caller Supplied Input Route cine x B peer hne be b Ups 87 ThedTnspeetior i000 oi erre des so 88 A Simple Decodinp Example ci ethan e IRI dail eda nun rci EDE a laced ache 89 Explanatory Text for Numbered Comments 2 nere ra IR HD PU ER S res 92 MIME Message Decoding Simple Example Output ooooococoococconcocanrancnnann nos 93 The Output DESTA eec cee ete nae tage eta tenes E a E a bake 93 Oe PIE RE ERR dea a Fu E hesitate 93 Calles Supplied Output Routine cia ie it 94 Decode onte 7 94 A Simple Virus Scanner Example eoe id nos tU ERR exer E tine Ri ot 95 Example Opin Ple cuneos o oie 106 Sample InputMessase sad ERAN 2 RUPES ER ARS 106 Explanatory Text for Numbered Comments rr c mere RE RES 107 Decoding MIME Messages Complex Example Output 00 0c cece eee eens 108 Chapter 6 MTA SDK Reference 200 cece eee eee eee eee eee eee 111 Summary OF SDK ROUHBeS a Rhee eed ee eee ea ee 111 Address Parsing love ME ve edhe Pde Her PP ted toh Pde os 112 5 Contents isceceti eR BER ER CERES PONC
35. Developer s Reference 148 mtaDecodeMessagelnfoString Example char buf 64 strcpy buf us ascii mtaOptionString mtaDecodeMessageInfoParams dctx MTA DECODE CTYPE PARAMS NULL charset 0 buf NULL sizeof buf printf Message part s character set is s n buf mtaDecodeMessagelInfoString Obtain string valued information relating to the current message part Syntax const char mtaDecodeMessageInfoString mta decode t dctx int item const char str size t len Arguments Arguments Description dctx A decode context created by mtaMessageDecode item Item identifier specifying which string value item to return See the description that follows for the list of permitted values for this argument str An optional pointer to receive the address of the requested string The string will be NULL terminated A value of NULL may be passed for this argument len An optional pointer to receive the length of the requested string This length is measured in bytes and does not include the NULL terminator at the end of the string A value of NULL may be passed for this argument Description This routine is used to obtain string valued information about the current message part When mtaDecodeMessage calls either a user supplied inspection or output routine it provides a decode context describing the current message part being processed Chapter 6 MTA SDK Reference 9 mtaDecod
36. MTA_BADARGS This value was returned for one of the following reasons 1 A NULL value was supplied for the dg ctx call argument 2 Aninvalid dequeue context was supplied for dq_ctx 3 Arequired argument to an item code was NULL MTA NOSUCHITEM An invalid item code was specified MTA THREAD The MTA SDK detected simultaneous use of the dequeue context by two different threads Example This code fragment assumes a condition in which the recipient address is invalid It returns a disposition of MTA DISP FAILED with an explanation mtaDequeueRecipientDisposition dq ctx sue siroe com 0 MTA DISP FAILED MTA REASON Invalid recipient address no such user 0 0 mtaDequeueRecipientNext Obtain the next envelope recipient address for the queued message file Chapter 6 MTA SDK Reference 9 mtaDequeueRecipientNext Syntax int mtaDequeueRecipientNext mta_dq_t dq ctx const char env to size t env to len int item code Arguments Argument Description dq ctx A dequeue context created by mtaDequeueStart env to Optional address of a pointer to receive the memory address of the next envelope recipient address The recipient address will not be NULL terminated env to len Optional address of a size t to receive the length of the returned recipient address A value of NULL may be passed for this argument item code An optional list of item codes See the description section that follows
37. Values Return Values Description 0 Normal successful completion TA BADARGS A NULL value was supplied for the opt ctx call argument TA FOPEN Unable to open the option file File access permissions are the likely cause for this error TA NO An error occurred while reading or parsing the option file TA NOMEM Insufficient virtual memory TA STRTRUERR The supplied file path is too long Its length must not exceed ALFA SIZE bytes Example opt ctx NULL if mtaOptionStart amp opt ctx NULL 0 0 Error loading the option file xy else if opt_ctx Option file did not exist mtaOptionString Return an option s value as a string Chapter 6 MTA SDK Reference 5 Syntax int mtaOptionString mta opt t opt ctx const char name size t len const char str size t str len size t str len max Description An option context created by mtaOptionStart A NULL value is permitted for this argument When a NULL is passed then no option value is returned Name of the option to obtain the value for The length of this string should not exceed ALFA SIZE bytes This string must be NULL terminated if a value of zero is passed for 1en Length in bytes not including any NULL terminator of the option name supplied with name If a value of zero is supplied then the option name string must be NULL terminated A pointer to a buffer to receive the NULL terminated value of the
38. addresses to be parsed The string must be NULL terminated if a value of zero is passed for address list len address list len The length in bytes of the string of addresses to parse not including any NULL terminator If a value of zero is passed for this argument then the length of address list will automatically be determined item code An optional list of item codes The list must be terminated with an integer argument with value 0 Description This routine parses a list of one or more comma separated RFC 822 addresses The input list can be of any arbitrary length The result of the parse is represented by an address context and a count of the parsed addresses Each parsed address can then be individually extracted from the parsed list with a call to ntaAddresGetN The address context should be disposed of with a call to mtaAddressFinish When there are no valid addresses in the input line the returned context will be NULL and the count zero NOTE There are two item codes that can be used in the item code argument A NULL value can be passed for either or both of the adr ctx and address count arguments When NULL is passed for both all that is learned by calling the routine is whether or not the address list is syntactically valid mtaAddressParse 122 Messaging Server 6 2005Q1 MTA Developer s Reference mtaAddressToChannel The following table lists the item codes for this routine their additional requi
39. an envelope only To address that is an active recipient which should not appear in the message s header The item address and item length fields specify the address and length of a string containing a To address The length of the address may not exceed ALFA SIZE bytes MTA FRAGMENT BLOCKS Specify the maximum number of blocks per message If when the message is enqueued the message size exceeds this limit then the message will be fragmented into smaller messages each fragment no larger than the specified block size The individual fragments are MIME compliant messages that use MIME s Chapter8 mtaSend Routine Specification 257 message partial content type MIME compliant mailers or user agents that receive the fragments may automatically re assemble the fragmented message MTA channels must be marked with the defragment keyword in order for automatic message re assembly to occur The size of a block may vary from site to site Sites can change this value from its default value of 1 024 bytes Use the MTA SDK routine mtaBLOCK SIZE to determine the size in bytes of a block The item length field specifies the maximum block size per message or message fragment By default no limit is imposed MTA FRAGMENT LINES Specify the maximum number of message lines per message If when the message is enqueued the number of message lines exceeds this limit then the message will be fragmented into smaller messages each fragment wit
40. arguments 1 The disposition string 2 The length in bytes of that string If a value of zero is passed for the length then the disposition string must be NULL terminated Specify the language used for the message part for example en r This language information will be placed in a Content language header line The item code must be followed by two additional call arguments 1 The language string 2 The length in bytes of that string If a value of zero is passed for the length then the string must be NULL terminated Chapter 6 MTA SDK Reference 153 Additional Arguments const char charset size t charset len const char disposition size t disposition len const char language size t language len E CCHARSE E CDISP E CLANG Item Codes MTA DECODI MTA DECODI MTA DECODI Description Specify the content subtype for the message part for example plain or html for text plain or text html This subtype information will be combined with the type and charset information and placed in a Content type header line The item code must be followed by two additional call arguments 1 The language string 2 The length in bytes of that string If a value of zero is passed for the length then the string must be NULL terminated Specify the major content type for the message part for example text for text plain or text html This major type information will be combined wit
41. be disabled For further details on the use of this item code see Required Privileges on page 241 This item code must be used in conjunction with MTA PRIV DISABLE PROC The item length field is ignored for this item code MTA SUBADDRESS Specify a subaddress to use when generating a return address from a user name specified with the MTA USER item code The item address and item length fields specify the address and length of a text string containing the subaddress The length of the string may not exceed ALFA_SIZE bytes Only one subaddress may be specified per message The MTA USER action must be used in conjunction with this item code Chapter8 mtaSend Routine Specification 263 MTA SUBJECT Specify the body of a Subject header line The item address and item length fields specify the address and length of a text string to place in the body of a Subject header line The length of the string may not exceed ALFA SIZE bytes Only one Subject body may be specified MTA TO Specify a To address that should appear in both the message s header and envelope The item address and item length fields specify the address and length of a string containing a To address The length of the address may not exceed ALFA SIZE bytes MTA USER Specify the user name to use for the envelope From and header line From addresses The item address and item length fields specify the address and length of a text string containing t
42. be responsible or liable for any actual or alleged damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content goods or services that are available on or through such sites or resources Sun Welcomes Your Comments Sun is interested in improving its documentation and welcomes your comments and suggestions 16 Messaging Server 6 2005Q1 MTA Developer s Reference Sun Welcomes Your Comments To share your comments go to http docs sun com and click Send Comments In the online form provide the document title and part number The part number is a seven digit or nine digit number that can be found on the title page of the book or at the top of the document For example the title of this book is Sun Java System Messaging Server 200501 MTA Developer s Reference and the part number is 819 0107 10 Preface 7 Sun Welcomes Your Comments 18 Messaging Server 6 2005Q1 MTA Developer s Reference Part MTA SDK Chapter 1 MTA SDK Concepts and Overview Chapter 2 MTA SDK Programming Considerations Chapter 3 Enqueuing Messages Chapter 4 Dequeuing Messages Chapter 5 Decoding Messages Chapter 6 MTA SDK Reference Chapter 1 MTA SDK Concepts and Overview The Sun Java System Messaging Server MTA SDK is a low level interface with routines falling into three categories those that enqueue messages those that dequeue messages and miscellaneous routines that typical
43. de controle des exportations et la liste de ressortissants specifiquement designes sont rigoureusement interdites LA DOCUMENTATION EST FOURNIE EN L ETAT ET TOUTES AUTRES CONDITIONS DECLARATIONS ET GARANTIES EXPRESSES OU TACITES SONT FORMELLEMENT EXCLUES DANS LA MESURE AUTORISEE PAR LA LOI APPLICABLE Y COMPRIS NOTAMMENT TOUTE GARANTIE IMPLICITE RELATIVE A LA QUALITE MARCHANDE A L APTITUDE A UNE UTILISATION PARTICULIERE OU A L ABSENCE DE CONTREFACON Contents 3 Contents Preface sass teeta aba a dew bea ead RUNE Rd Who Should Use This Book cec Before You Read This Book How This Book Is Organized Conventions Used in This Book Typographic Conventions Symbols coria fereriex wee ihe Default Paths and File Names Command Line Prompts esee Related Documentation seus Messaging Server Documents Communications Services Documents Accessing Sun Resources Online Contacting Sun Technical Support Related Third Party Web Site References Sun Welcomes Your Comments MTA SDK iii d ei Chapter 1 MTA SDK Concepts and Overview Channel Programs and Message Queuing Managing Multiple Threads Contexts Enqueuing Messages 000 e cece eens Message Components siosee ike med Envelope cbr ar a Part Reade PTT
44. do not insert a blank line between the input from one source and the next This is the default behavior the input from each input source is appended one after the other with no delimiters or separators marking the transition between sources The item address and item length fields are ignored for this item code Item Codes 262 Messaging Server 6 2005Q1 MTA Developer s Reference Item Codes MTA NOIGNORE ERRORS Send the message only if all To addresses are okay and all input sources are okay This is the default The item address and item length fields are ignored for this item code MTA PRIV DISABLE PROC The address of a procedure to invoke immediately after enqueuing a message so as to disable process privileges See the description of MTA PRIV ENABLE PROC for details on the use of this item code This item code must be used in conjunction with MTA PRIV ENABLE PROC item The item length field is ignored for this item code MTA PRIV ENABLE PROC The address of a procedure to invoke immediately before enqueuing a message so as to enable process privileges Privileges are required to enqueue messages It is possible to provide mtasend with the address of two procedures to call One procedure is called immediately prior to enqueuing a message thereby allowing process privileges to be enabled The second procedure is then called immediately after the message has been enqueued thereby allowing process privileges to
45. enqueue mta nq t ng const char channel mtaEnqueueStart ng sue siroe com 0 0 mtaEnqueueInfo nq MTA CHANNEL amp channel NULL 0 printf Source channel s n channel mtaEnqueueStart Initiate a message submission Chapter 6 MTA SDK Reference 3 Syntax int mtaEnqueueStart mta nq t ng const char env from size t env from len int item code Description On a successful return a pointer to an enqueue context created by mtaEnqueueStart This enqueue context represents the message enqueue operation initiated by the call Optional pointer to the address to use as the envelope From address for the message being submitted The address must be compliant with RFC 2822 When used as an envelope address the MTA will reduce it to an RFC 2821 compliant transport address The string must be NULL terminated if a value of zero is passed for env rom len The length of this string not including any NULL terminator may not exceed ALFA SIZE bytes A value of NULL may be supplied for this argument When that is done the env from len argument is ignored and an empty envelope From address is used for the message submission The length in bytes not including any NULL terminator of the envelope From address supplied with env rom If a value of zero is passed for this argument then the envelope From address string must be NULL terminated An optional list of item codes See
46. envelope From address for a message should be specified with the MTA_USER item code With this item code only the local part of a mail address may be specified that is the user name The mtaSend routine will automatically append the official local host name to the user name so as to produce a valid mail address The MTA_ENV_FROM item code may be used to explicitly specify a complete envelope From address but this is usually not necessary Applications that enqueue nonlocal mail should probably be using the SDK routines rather than mtaSena Messaging Server 6 2005Q1 MTA Developer s Reference 238 To Cc and Bcc Addresses If neither MTA USER nor MTA ENV FROM are specified then the user name associated with the current process will be used for the envelope From address When MTA USER is used the From header line will be derived from the envelope From address When ENV FROM is used the From header line will be derived from the user name of the current process In either case if a From header line is supplied in an initial header then a Sender header line will be added to the message header The initial From header line will be left intact and the address specified and Sender address will be derived from either the envelope From address MTA USER or from the user name of the current process that is from MTA ENV FROM Only privileged users may use MTA USER to specify a user name different than
47. final array entry with an item code value of 0 For further information on item lists see Item Codes and Item Lists on page 28 Additional Arguments None None size t level None None mta item list t item list mtaDebug Item Codes Continued 5 Lu EQUEUE MTA DEBUG DI MTA DEBUG ENQUEUI MTA DEBUG MM MTA DEBUG OS MTA DEBUG SDK MTA ITEM LIST 134 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDecodeMessage Return Values Return Values Description 0 Successful normal completion MTA BADARGS A NULL value was supplied for a pointer to an item list array MTA FOPEN Unable to initialize the MTA SDK Unable to read one or more configuration files For further information issue the following command imsimta test rewrite MTA NO Unable to initialize the MTA SDK For further information issue the following command imsimta test rewrite MTA NOSUCHITEM An invalid item code was specified Example mtaDebug MTA DEBUG SDK MTA MM DEBUG 8 0 mtaDecodeMessage Decode a MIME formatted message optionally convert non MIME formats to MIME Syntax int mtaDecodeMessage void 0 int input type void input int output type void output mta decode inspect t inspect int item code Arguments Arguments Description ctx Optional pointer to a caller supplied context or other data type This pointer will be passed as the ct x argument to any caller
48. followed by a blank line followed by any message content Each call to this routine must supply a single complete line of the message The line should not include a line feed terminator as mtaEnqueueWriteLine will supply the terminator automatically Calling mt aEnqueueWriteLine terminates the message s envelope recipient list Once the routine is called mtaEnqueueTo can no longer be called for the same enqueue context Description Normal successful completion This value is returned for one of the following reasons 1 A NULL value was supplied for the ng ctx call argument 2 An invalid enqueue context was supplied for ng ctx or a required argument to an item code was NULL Unable to create a disk file Error writing to a disk Call made out of order No envelope recipient addresses have been supplied Simultaneous use of the enqueue context by two different threads was detected Return Values Return Values 0 MTA BADARGS MTA FCREATE MTA FIO MTA ORDER MTA THREAD mtaEnqueueWriteLine 210 Messaging Server 6 2005Q1 MTA Developer s Reference mtaErrno Example This code fragment writes out two header lines mtaEnqueueWriteLine nq From sue siroe com 0 NULL mtaEnqueueWriteLine ng Subject test 0 NULL This code fragment shows the header output as a result of the preceding code example From sue siroe com Subject test The following code fragmen
49. following code fragment shows the required syntax of an inspection routine int inspection_routine void XOU mta decode t dctx int data type const char data size t data len Chapter 6 MTA SDK Reference 7 The following table lists each of the inspection routine s arguments and gives a description of each Arguments Description ctx The caller supplied private context dct x A decode context created by mt aDecodeMessage This decode context represents the current part being processed This context is to be used with calls to the other decode routines requiring a decode context This context is automatically disposed of by mtaDecodeMessage data_type The nature of the data being presented Fora header line MTA_DATA_HEADER For a line of text based content DATA TEXT For a line of binary content MT DATA BINARY No data at all DATA NONE Atomic part content with a MIME content type of text or message is considered to be text based Such content is given the data type MTA DATA TEXT All other atomic part content audio image and application is considered to be binary and denoted by the data type MTA DATA BINARY The data type MTA DATA NONE is only presented when using an optional output routine supplied with the output argument in mtaDecodeMessage data A pointer to the data being presented Message lines will not have carriage return or line feed terminators no
50. in units of blocks By default a block is 1024 bytes However sites may change that size with the MTA BLOCK SIZE option Consequently code using this option should use the mtaBlockSize option should they need to convert some other unit to blocks This item code must be followed by one additional argument the block size threshold to impose By default no threshold is imposed Additional Arguments const char env id size t env id len size t limit size t blocks mtaEnqueueStart Continued Item Codes MTA_ENV_ID MTA_EXPAND_LIMIT ENT_BLOCKS MTA FRAGMI 198 Messaging Server 6 2005Q1 MTA Developer s Reference mtaEnqueueStart Description A large enqueued message can be automatically fragmented into several smaller messages using the MIME content type message partial At the destination MTA system these smaller messages can be automatically re assembled back into one single message The MTA_FRAGMENT_LINES item code allows specification of a line count threshold for which messages exceeding the threshold will automatically be fragmented This item code must be followed by one additional argument the line count threshold to impose By default no threshold is imposed Specify the delivery status notification flags to be set for the entire message The specified value is a bit map constructed using the MTA NOTIFY constants defined in mt asdk h If no setting is made then the value from a
51. is shared by all dequeue threads calling process message as a result of a given call to mtaDequeueStart The global context in this example provides process message with the following 1 How many messages to put into a BSMTP file before closing it and starting a new one and 2 Whether or not to produce diagnostic debug output See explanatory comment 3 gctx debug 1 gctx max count 5 Start the dequeue loop See explanatory comment 4 ires mtaDequeueStart void amp gctx process message process done 0 Check the return status See explanatory comment 5 if lires Success return 0 Produce an error message See explanatory comment 6 mtaLog mtaDequeueStart returned d s ires mtaStrError ires 0 And exit with an error returnh 1 64 Messaging Server 6 2005001 MTA Developer s Reference A Complex Dequeuing Example Code Example 4 2 A Complex Dequeue Example Continued process done Called by mtaDequeueStart to clean up and destroy a per thread context created by process message See explanatory comment 7 z static void process_done void my_ctx_2 void my_ctx_1 my global context t gctx my global context t my ctx 1 my thread context t tctx my thread context t my ctx 2 if tctx return Generate any requested diagnostic output requested See explanatory
52. it you may either code the channel name into your program or specify it through your run time environment with the CHANNEL environment variable For example to do the latter on UNIX platforms use a command of the following form PMDF CHANNEL channel name program name where channel name is the name of the channel and program name is the name of the executable program to run In production if your program will run as a master or slave channel program under the MTA Job Controller then you do not need to specify the channel name it will automatically be set by the Job Controller using the PMDF CHANNEL environment variable If however your program will be run manually or as a server then either the program can specify its channel name through code or using the PMDF CHANNEL environment variable For the latter setting the environment variable is typically achieved by wrapping your executable program with a shell script The shell script would set the environment and then invoke your program as illustrated in the following code example bin sh PMDF CHANNEL channel name PMDF CHANNEL OPTION option file path export PMDF CHANNEL PMDF CHANNEL OPTION program name exit Note that the option file path shown in the previous example is the full absolute path to the channel s option file if any A program can query the SDK to determine what channel name is being used with either the mtaChannelGetName mtaEnqueue
53. item lists the number of items passed to an SDK routine must be known at compile time That is it is difficult if not impossible for a program at run time to adjust the number of item codes that it wishes to pass In recognition of this limitation all SDK routines that accept an item code list also accept a pointer to an arbitrary length array of item codes Such an array is referred to as an item list array and is specified with the MTA ITEM LIST item code This mechanism allows programs to dynamically construct the array at run time while still using a fixed number of arguments at compile time The MTA ITEM LIST item code is always followed by an additional call argument whose value is a pointer to an array of mta item list t type elements Each array entry has the following five fields Description An item code value indicating an action to be effected The permitted item code values are routine specific Fields int item code const void item address The caller suppled address of data to be used in conjunction with the action specified by the item code field Not all actions require use of this field 28 Messaging Server 6 2005Q1 MTA Developer s Reference Item Codes and Item Lists Description When the item code has an associated string value this field optionally provides the length in bytes of the string not including any NULL terminator If a value of zero is supplied then the string pointed at by the item add
54. line of a notification message mtaEnqueueWriteLine ng From Postmaster gt 0 mtaPostmasterAddress NULL NULL 0 0 gt 0 NULL mtaStackSize Obtain the minimum thread stack size required when using the MTA SDK Syntax size_t mtaStackSize void Arguments None Description A number of the run time libraries used by the MTA SDK make intensive use of stack variables As a result some MTA SDK operations can require a larger than usual thread stack size The minimum thread stack size required for typical MTA SDK operations such as message dequeue and enqueue operations can be obtained with mtaStackSize When writing multi threaded code ensure that any threads that will be calling SDK routines have a stack size at least as large as the value returned by mtaStacksSize Failure to do may result in abnormal process terminations when a thread overruns its stack Return Values The minimum thread stack size required for MTA SDK operations Example None Chapter 6 MTA SDK Reference 229 mtaStrError mtaStrError Obtain a text description of an error status code Syntax const char mtaStrError int code int item code Arguments Arguments Description code The MTA SDK error status to obtain a text description for item code Reserved for future use A value of zero must be supplied for this call argument Description Use mtaStrError to obtain English language descriptions
55. lt 0x01 gt lt 0x01 gt xj default copy after translating to lower case A Simple Virus Scanner Example Code Example 5 2 Decoding MIME Messages Complex Example Continued buf 0 7 07 mtaOptionString channel opts BAD MIME TYPES 0 buf amp buflen sizeof buf Now translate the comma separated list Typel Subtypel Type2 Subtype2 to Xx AR A x ptr0 buf ptrl options bad mime types ptrit char 0x01 for i 0 i gt buflen 1 if ptrO ptrl tolower ptr0 else ptrl char 0x01 ptr0 ptrit char 0x01 ptrl 0 options bmt len ptrl options bad mime types BAD FILE TYPES Ext1 Ext2 kf buf 0 N0 buflen 0 mtaOptionString channel opts BAD FILE TYPES 0 buf amp buflen sizeof buf Now translate the comma separated list Ext1 JExt2 Lo lt 0x01 gt ext1 lt 0x01 gt ext2 lt 0x01 gt lt 0x01 gt ptr0 buf ptrl options gt bad_file types ptrit char 0x01 for i 0 i gt buflen i switch ptr0 ptrl 6010762 ptrO0 Messaging Server 6 2005021 MTA Developer s Reference 104 A Simple Virus Scanner Example Code Example 5 2 Decoding MIME Messages Complex Example Continued break case discard break case end current type ptrl 082
56. make use of ctx2 but ctxl is a pointer to our channel options See explanatory comment 4 static int process message void ctx2 void ctxl mta dq t dq const char env from size t env from len Chapter 5 Decoding Messages Decoding MIME Messages Complex Example Continued const char adr disp ires e t len mta nq t ng our options t options our options t ctxl Initializations NULL A little macro to do error checking on mta calls CHECK f x ires error_report options ires f goto done bad Start a message enqueue Use the dequeue context to copy envelope flags fromt the current message to this new message being enqueued See explanatory comment 5 CK mtaEnqueueStart mtaEnqueueStart ng env from env from len DQ CONTEXT dq 0 Process the envelope recipient list See explanatory comment 6 le ires mtaDequeueRecipientNext dq amp adr amp len 0 Add this envelope recipient address to the message being enqueued Use the dequeue context to copy envelope flags for this recipient from the current message to the new message ires mtaEnqueueTo ng adr len MTA DQ CONTEXT dq MTA ENV TO 0 See explanatory comment 7 disp ires MTA DISP DEFERRED MTA DISP RELAYED CHECK mtaDequeueRecipientDisposition mtaDequeueRecipientDisposition dq adr len disp 0 A normal exit from th
57. mta opt t opt ctx const char path size t len int item code Arguments Arguments Description opt ctx On successful return a pointer to an option context created by mtaOptionStart This option context represents the options read from the option file path Optional file path to the option file to read If not specified then the path specified by the PMDF CHANNEL OPTION environment variable will be used If a value of zero is supplied for 1en and there is a non NULL value for path the value must be NULL terminated The length of the file path not including any NULL terminator may not exceed ALFA SIZE bytes len Length in bytes not including any NULL terminator of the file path This argument is ignored when a NULL is passed for path When path is non NULL and a value of zero is supplied for 1en then the file path string must be NULL terminated item code Reserved for future use A value of zero must be supplied for this call argument Description MTA option files such as channel option files may be read parsed and loaded into memory with mtaOptionStart Once loaded into memory the values of individual options may be retrieved with the routines shown in the table that follows Routine Names Description mtaOptionFloat Retrieve the value of a floating point valued option mtaOptionInt Retrieve the value of an integer valued option mtaOptionString Retrieve the string representation of an options value Thes
58. routine When called by one of the mtaDequeueStart execution threads the processing routine uses the SDK to access the message s envelope header and any content Upon completion of processing the message is then either removed from the MTA queues or in the event of a temporary error left in its queue for a later processing attempt Chapter 4 Dequeuing Messages 51 Caller Supplied Processing Routine Dequeue Message Processing Routine Tasks The processing routine processes a single queued message per invocation The specific steps that a processing routine takes are 1 Read the envelope recipient list with repeated calls to mtaDequeueRecipientNext When mtaDequeueRecipient returns the MTA EOF status code the list has been exhausted and all envelope recipient addresses have been provided AII queued messages are guaranteed by the MTA to always have at least one envelope recipient address 2 Read the message both header and body with repeated calls to mtaDequeueLineNext When ntaDequeueLineNext returns the MTA_EOF status code the message has been exhausted that is there is no more message text to retrieve The message will be an RFC 2822 conformant message As such the division between the message s header and content will be demarked by a blank line a line with a length of zero A message may have no content that is a message may have just a header 3 Process the message The processing i
59. size t to receive the length in bytes of the returned host name This length does not include the NULL terminator that terminates the host name A value of NULL can be passed for this call argument item code An optional list of item codes The list must be terminated with an integer argument with value 0 Description This routine is used to determine the host name associated with a particular channel The channel name can be specified in one of three ways e Implicitly specified For this case no item codes other than the terminating 0 are specified and the channel name is the one for the running program The channel name is set using the PMDF CHANNEL environment variable e Explicitly specified with the MTA CHANNEL item code Setusing the MTA DQ CONTEXT item code which is taken to be the channel name associated with a specified dequeue context In all cases the official host name of the selected channel is the host name that is returned The official host name for a channel is the one that appears on the second line of the channel definition in the MTA configuration file imta conf Chapter 6 MTA SDK Reference 129 mtaChannelToHost The following table lists the item codes and any associated arguments Description Explicitly specify a channel name for the official host name This item code must be followed by the two additional call arguments specifying 1 The channel name 2 The length in bytes of t
60. smessage points to a NULL terminated string containing the rewritten form of the address When item status has a non zero value item smessage points to a NULL terminated string containing an error message suitable for printing for diagnostic purposes Chapter7 Using Callable Send mtaSend 239 To Cc Message Headers and Content Message Headers and Content The body of a message that is the message content is built up from zero or more input files or procedures The input files and procedures are read or invoked in the order specified in the item list passed to the mtasend routine The message body is built up by appending the next input source to the end of the previous input source A blank line will be inserted in the message as a separator between input sources if the MTA BLANK item is requested in the item list The MSG FILE and MTA MSG PROC item codes are used to specify the name or address of input files or procedures An initial message header may be supplied from either an input file or procedure The message header will then be modified as needed when the message is enqueued The MTA HDR FILE and MTA HDR PROC items are used to specify the name or address of an input file or procedure If an initial message header is to be supplied it must appear in the item list before any MTA MSG FILE or MTA MSG PROC items A blank line must be supplied at the end of the message header or at the start of the first message body i
61. supplied address of data to be used in conjunction with the action specified by the item code field Not all actions require that an item address be supplied item length When the item code has an associated string value this field optionally provides the length in bytes of the string not including any NULL terminator If a value of zero 0 is supplied then the string pointed to by item address must be NULL terminated so that mtaSend can automatically determine the string s length When the item code has an associated integer value this field supplies that value item status When the item code MTA ADR STATUS is specified this field will contain processing status for the associated envelope recipient address item smessage When the item code MTA ADR STATUS is specified this field will contain the rewritten form of the envelope recipient address when the returned value of item status is zero or a textual error message when the returned value of item status is non zero Description Use mtaSend to send a message The routine performs the processing carried out to address the message generate the message s header and body and enqueue the message as specified with the item list argument For instructions on how to use mtaSend see Chapter 7 Using Callable Send mtaSend mtaSend Syntax 252 Messaging Server 6 2005Q1 MTA Developer s Reference Item Codes Item Codes MTA ADR NOSTATUS Do not return status message
62. supplied dequeue context will be used If no dequeue context is supplied then the MTA default value is used The default value is MTA_NOTIFY_DELAY MTA_NOTIFY_FAILURE MTA_NOTIFY_CONTENT_FULL Flags for individual recipient address may be specified when mtaEnqueueTo is called This item code must be followed by one additional call argument the address of an integer to receive the setting of the delivery status notification flags Chapter6 MTA SDK Reference 199 Additional Arguments size_t lines size_t nflags Item Codes Continued MTA_FRAGMENT_LINES MTA_NOTIFY_FLAGS mtaEnqueueTo Return Values Return Values Description 0 Normal successful completion MTA BADARGS This value is returned for one of the following reasons 1 A NULL value was supplied for the ng ctx call argument 2 An invalid enqueue context was supplied for nq ctx 3 Arequired argument to an item code was NULL TA NO Unable to determine the channel name from the CHANNEL environment variable TA NOMEM Insufficient virtual memory TA NOSUCHCHAN Specified channel name does not exist in the MTA configuration TA NOSUCHITEM An invalid item code was specified TA STRTRUERR The supplied envelope From address is too long it may not exceed a length of ALFA_SIZE bytes Or the supplied channel name has a length exceeding CHANLENGTH bytes Example This routine is used as part of Decoding MIME
63. supplied routines such as the one supplied as the inspect argument A value of NULL can be passed for this argument Chapter 6 MTA SDK Reference 135 Arguments Description input type Input type indicator describing the input source to use either a dequeue context or a caller supplied routine There are only two valid values MTA DECODE DQ MTA DECODE PROC input For input type MTA DECODE DQ input must be a pointer to a dequeue context created by mtaDequeueStart For input type MTA DECODE PROC input must be the address of a routine of type mta decode read t output type Optional output type indicator describing the output destination to use either an enqueue context or a caller supplied routine Valid values are 0 MTA DECODE NQ MTA DECODE PROC When a value of 0 is supplied the output argument is ignored output Foroutput type MTA DECODE output must be a pointer to an enqueue context created with mt aEnqueueStart For output type MTA DECODE PROC output must be the address of a routine to type mta decode write t This argument is ignored when a value of 0 is supplied for output type inspect The address of an inspection routine of type mta decode inspect t item code An optional list of item codes The list must be terminated with an integer argument with value 0 Description The MTA has powerful facilities for parsing and decoding single and multipart messages formatted usi
64. the message being dequeued is removed from the MTA queues 15 Intheevent of an error the new message enqueue is cancelled and the current message left in the queues for later processing 16 The rot13 character transformation 17 Aroutine that applies the rot13 transformation to a character string Chapter 4 Dequeuing Messages 9 Thread Creation Loop in mtaDequeueStart Sample Input Message for the Intermediate Channel Example The example that follows is a sample input message from the queue to be processed by the program found in Code Example 4 3 on page 73 Received from frodo west siroe com by frodo west siroe com Sun Java System Messaging Server 6 200402 built Mar 24 2004 id OHCH00301E6GO7008frodo west siroe com for sue sesta com Fri 28 Mar 2003 14 51 52 0800 PST Date Fri 28 Mar 2003 14 51 52 0800 PST From root frodo west siroe com Subject Testing To sue sesta com Message id 0HCH00303E6GO70080frodo west siroe com MIME version 1 0 This is a test message Output from the Intermediate Channel Example This example shows the output generated by the dequeue and re enqueue program Code Example 4 3 on page 73 Received from sesta com by frodo west siroe com Sun Java System Messaging Server 6 200402 built Mar 24 2003 id OHCH00301E7DOH00Gfrodo west wiroe com for sue sesta com Fri 28 Mar 2003 14 51 58 0800 PST Received from frodo west siroe com by frodo west siroe com Sun Jav
65. the description section that follows for a list of item codes The list must be terminated with an integer argument with value 0 Arguments Arguments nq ctx env from env from len item code Description To submit a message to the MTA for delivery an enqueue operation must be initiated This is achieved by calling mtaEnqueueStart When the call is successful an enqueue context representing the enqueue operation will be created and a pointer to the context returned via the nq ctx call argument This context must then be used to specify the message s envelope recipient list and content both header and body Once the recipient list and content have been specified the submission may be completed with mtaEnqueueFinish That same routine is also used to cancel an enqueue operation For further information on message enqueue processing see Basic Steps to Enqueue Messages on page 42 Enqueue contexts are disposed of with mtaEnqueueFinish either as part of completing or cancelling a message enqueue operation mtaEnqueueStart 194 Messaging Server 6 2005Q1 MTA Developer s Reference mtaEnqueueStart When initiating an enqueue operation the envelope From address for the message should be specified with the env rom and env_from_len call arguments or through use of a dequeue context with the MTA 20 CONTEXT item code In either case it is important to keep in mind the usage of the envelope From add
66. the input routine to supply the la message to be MIME decoded Messaging Server 6 2005001 MTA Developer s Reference 90 A Simple Decoding Example Code Example 5 1 Decoding MIME Messages Continued 2 Use decode inspect as the routine to inspect each MIME decoded message part 3 Do not specify an output routine to write the resulting MIME message and 4 Indicate that the input message source uses LF record terminators See explanatory comment 3 mtaDecodeMessage void amp pos MTA DECODE PROC void decode read 0 NULL decode inspect MTA TERM LF 0 x A HF H decode read Provide message data to mtaDecodeMessage The entire message could just as easily be given to mtaDecodeMessage at once However for illustration purposes the message is provided in 200 byte chunks See explanatory comment 4 static int decode read void ctx const char line size t line len position_t pos position_t ctx if pos return MTA_NO else if pos cur position gt pos end position return MTA_EOF line pos gt cur_position line_len pos gt cur_position 200 gt pos end position 200 pos end position pos cur position pos cur position line len return MTA OK decode inspect Called by mtaDecodeMessage to output a X a line of the parsed message The line is i simply output with additional information indicatin
67. the value specified with this item code This item code should be followed by an additional call argument the delivery flag setting to effect When a dequeue context is supplied with this item code the message submission will take all of its envelope fields except for the recipient list from the envelope of the queued message represented by the dequeue context including the envelope From field These assumed settings can then be overridden on an individual basis through the use of other item codes and the env fromand env from len call arguments Use of this item code changes the defaults for the envelope fields from the MTA defaults to the values used in the dequeue context Intermediate processing channels are strongly encouraged to use this item code Use of this feature allows envelope information to be automatically copied from the queued message being processed to the new message that will be enqueued as a result This item code must be followed by one additional argument the pointer to the dequeue context to use Chapter 6 MTA SDK Reference 7 Additional Arguments char channel size t channel len size t dflags size t dflags mta dq t dq ctx Continued EL ERY FLAGS ERY FLAGS ABS Item Codes MTA CHANNI MTA DELIVI MTA DELIVI MTA DO CONTEXT Description Explicitly specify an envelope ID string for the message The supplied value must conform to the syntax of an xtext o
68. top of the imta cnf file siroe com SU siroe com8x looptest daemon SNxloop test siroe com U siroe com The new rewrite rule causes the following to happen When a new inbound or outbound message for user siroe com is enqueued to the xloop text channel it processes the message and re enqueues it to user siroe com Inthe new rewrite rule N says that the first new rewrite rule is to be ignored when the xloop_test channel itself enqueues a message e Therefore after the x1oop test channel does its processing and re enqueues the message to user siroe com the first new rewrite rule is ignored and the second old rule is then applied causing the message to be routed as it would have been before the x1oop test channel was added to the MTA Chapter 2 MTA SDK Programming Considerations 7 Miscellaneous Programming Considerations Miscellaneous Programming Considerations This section covers miscellaneous topics of interest to programmer s using the SDK e Retrieving Error Codes on page 38 e Writing Output From a Channel Program on page 38 e Considerations for Persistent Programs on page 38 Retrieving Error Codes With few exceptions all routines in the SDK return an integer valued result with a value of zero 0 indicating success When a non zero value is returned it is also saved in a per thread data section which may be retrieved with either the mtaErrno function or the mta_errno
69. 00 Dequeue thread starting id 3 context 32600 16 82 Dequeue thread s S S S 17 04 Dequeue thread starting id 4 context 32618 S S S S 16 87 Dequeue thread 17 09 Dequeue thread starting id 5 context 32630 17 14 Dequeue thread starting id 6 context 78e50 17 19 Dequeue thread starting id 7 context 88a18 17 23 Dequeue thread starting id 9 context 8ab78 17 51 Dequeue thread starting id 8 context 8ab60 19 96 Dequeue thread done id 2 context 325e8 messages 12 19 96 Dequeue thread done 10 5 context 32630 messages 22 19 97 Dequeue thread done id 6 context 78e50 messages 11 19 97 Dequeue thread done id 4 context 32618 messages 5 19 98 Dequeue thread done id 8 context 8ab60 messages 16 20 00 Dequeue thread done id 9 context 8ab78 messages 5 20 00 Dequeue thread done id 3 context 32600 messages 12 20 01 Dequeue thread done id 1 context 32390 messages 7 20 02 Dequeue thread done id 10 context 32360 messages 6 20 03 Dequeue thread done id 7 context 88a18 messages 4 IA BB Bj p pp E o po io pp po ip p i i p p i S B5 3 C39 6 6 6 CO CJ C3 COO O9 06506000 Intermediate processing channels Special attention is warranted for intermediate processing channels Intermediate processing channels are channels which re enqueue back to the MTA the mail they dequeue from it For example a virus scanner or a co
70. 26 mtaChannelGetName 127 mtaChannelToHost 129 mtaDateTime 131 mtaPostmasterAddress 227 mtaStackSize 229 mtaUniqueString 230 mtaVersionMajor 231 mtaVersionMinor 232 mtaVersionRevision 232 mtaAccountingLogClose 114 117 mtaAddaressParse 112 mtaAddressFinish 112 mtaAddressGetN 112 118 mtaAddressParse 121 mtaAddressToChannel 114 123 mtaBlockSize 114 126 mtaChannelGetName 114 127 mtaChannelToHost 114 129 mtaDateTime 114 131 mtaDebug 114 133 mtaDecodeMessage 114 135 mtaDecodeMessagelnfoInt 114 145 mtaDecodeMessagelnfoParams 114 147 mtaDecodeMessagelnfoString 114 149 mtaDecodeMessagePartCopy 114 151 mtaDecodeMessagePartDelete 114 152 mtaDequeuelnfo 112 156 mtaDequeueLineNext 112 160 mtaDequeueMessageFinish 112 162 mtaDequeueRecipientDispoistion 112 mtaDequeueRecipientDisposition 165 mtaDequeueRecipientNext 112 169 mtaDequeueRewind 112 171 mtaDequeueStart 112 172 mtaDequeueStart multiple calls to 82 mtaDequeueThreadId 182 mtaDone 113 183 mtaEnqueueCopyMessage 113 183 mtaEnqueueError 185 mtaEnqueueFinish 113 187 timed out 53 rewrite rules preventing message loops 37 root running as 33 running test programs in a messaging environment 34 manually 34 36 runtime considerations 31 S sample programs complex dequeuing program 63 intermediate channel program 73 mtaSend sending a message to multiple recipients 245 mtaSend sending a simple message 243 mtaSend specifying an initial message header 244 mt
71. 3 Intermediate Channel Example Continued in header 1 while in header amp amp mtaDequeueLineNext dq amp line amp len if mtaEnqueueWriteLine nq line len 0 goto defer if len in_header 0 Determine why we exited the while loop i if in header We exited before seeing the body of the message See explanatory comment 12 if mta errno MTA EOF Message read completely it must have no body x goto done else Error condition of some sort x goto defer Now 20613 the body of the message See explanatory comment 13 while mtaDequeueLineNext dq amp line amp len if mtaEnqueueWriteLline ng rotl3str rot13 buf t my ctx 2 line len len 0 goto defer If mta errno MTA EOF then we exited the loop normally otherwise there s been an error of some sort if mta errno MTA EOF goto defer All done enqueue the new message See explanatory comment 14 done if mtaEnqueueFinish ng 0 amp amp ImtaDequeueMessageFinish dq 0 return 0 76 Messaging Server 6 2005001 MTA Developer s Reference Intermediate Channel Example Code Example 4 3 Intermediate Channel Example Continued Fall through to defer the message nq NULL A processing error of some sort has occurred defer the message for a later delivery attempt See explanatory comment 15 defer mtaDequeu
72. 5 mtaDecodeMessagelnfolnt on page 145 mtaDecodeMessagelnfoParams on page 147 mtaDecodeMessagelnfoString on page 149 mtaDecodeMessagePartCopy on page 151 mtaDecodeMessagePartDelete on page 152 mtaDequeuelnfo on page 156 mtaDequeueLineNext on page 160 mtaDequeueMessageFinish on page 162 mtaDequeueRecipientDisposition on page 165 mtaDequeueRecipientNext on page 169 mtaDequeueRewind on page 171 mtaDequeueStart on page 172 mtaDequeueThreadld on page 182 mtaDone on page 183 mtaEnqueueCopyMessage on page 183 mtaEnqueueError on page 185 116 Messaging Server 6 2005Q1 MTA Developer s Reference mtaAccountingLogClose Routine Name and Page Continued mtaEnqueueFinish on page 187 mtaEnqueuelnfo on page 189 mtaEnqueueStart on page 193 mtaEnqueueTo on page 200 mtaEnqueueWrite on page 206 mtaEnqueueWriteLine on page 209 mtaErrno on page 211 mtalnit on page 212 mtaLog on page 215 mtaLogv on page 217 mtaOptionFinish on page 218 mtaOptionFloat on page 219 mtaOptionInt on page 220 mtaOptionStart on page 222 mtaOptionString on page 225 mtaPostmasterAddress on page 227 mtaStackSize on page 229 mtaStrError on page 230 mtaUniqueString on page 230 mtaVersionMajor on page 231 mtaVersionMinor on page 232 mtaVersionRevision on page 232 mtaAccountingLogClose Close the MTA accounting log file mail log current
73. 56 mtaDequeueLineNext 160 mtaDequeueMessageFinish 162 mtaDequeueRecipientDisposition 165 mtaDequeueRecipientNext 169 mtaDequeueRewind 171 mtaDequeueStart 172 mtaDequeueThreadId 182 diagnostic facility enabling 33 documentation overview 15 where to find Communications Services documentation 15 where to find Messaging Server documentation 15 E enqueue context 24 enqueuing messages aborting 42 187 basic steps 42 bee 200 body 24 calling dependencies 47 ce 200 completing 187 components 22 copying 183 delivery receipts 199 204 L linking instructions MTA SDK 34 mtaSend 242 Linux default base directory for 14 list of MTA SDK routines 116 log file mail log current 39 logging and diagnostic routines mtaDebug 133 mtaLog 215 mtaLogv 217 loop message 37 mailloops 37 mail log current 39 manually running programs 32 master channels defined 21 message components body 23 envelope 23 header 23 message loop avoiding 37 message processing procedure 60 process done routine 62 syntax and arguments 54 messages dequeuing tasks 52 enqueuing 22 locking 25 Messaging Server documentation 15 MIME decoding routines mtaDecodeMessagelnfoInt 145 mtaDecodeMessagelnfoParams 147 mtaDecodeMessagelnfoString 149 mtaDecodeMessagePartCopy 151 mtaDecodeMessagePartDelete 152 MIME parsing 85 miscellaneous routines Section G G global context 64 H headers deriving 23 initial message header example 244 initialization
74. A When transferring a message originated elsewhere into the MTA programs should use the MTA ENV TO item code with mtaEnqueueTo This way each of the recipient addresses will only be added to the message s envelope and not to its already constructed header Additionally supply the message s header as is Do not remove or add any origination or destination header lines unless necessary Failure to use the TO item code will typically cause the SDK to add Resent header lines to the message s header A Complex Dequeuing Example on page 63 and A Simple Virus Scanner Example on page 95 both illustrate the use of the MTA ENV TO item code Intermediate Processing Channels Like programs which transfer messages into the MTA intermediate processing channels should also use the MTA TO item code with mtaEnqueueTo When re enqueuing a message intermediate processing channels should also preserve any MTA envelope fields present in the message being re enqueued This is done using the DQ CONTEXT item code in conjunction with mtaEnqueueStart and mtaEnqueueTo Failure to preserve these envelope fields can result in loss of delivery receipt requests special delivery flags and other flags which influence handling and delivery of the message A Complex Dequeuing Example on page 63 and A Simple Virus Scanner Example on page 95 both illustrate the use of the MTA ENV TO and MTA DQ CONTEXT item co
75. A Developer s Reference mtaAddressToChannel Description Use this routine to determine which channel an address rewrites to The address to be rewritten can be an envelope or header address and can be forward or reverse pointing The nature of the address is specified with the address type argument The following table lists the possible values for each combination forward pointing envelope reversing pointing envelope forward pointing header reverse pointing header Types of Address Value Forward pointing envelope address 0 BCC MTA CC MTA ENV TO MTA TO Reverse pointing envelope address MTA ENV FROM Forward pointing header address MTA HDR BCC MTA HDR CC MTA HDR TO Reverse pointing header address MTA HDR FROM In most cases a value of MTA TO is appropriate Other values will typically give the same result unless the MTA configuration has rewrite rules that are sensitive to the distinctions between the four types of addresses Return Values On successful operation the routine returns the value of the channel argument In the event of an error the value returned is NULL and the mta errno variable is set with an error status code The following table lists the error status codes and gives a description of each Error Status Codes Description MTA BADARGS There are two reasons to get this return value 1 A NULL value was supplied for the address argument 2 An invalid value was supplied for the a
76. A Developer s Reference 240 Required Privileges Required Privileges Like the MTA SDK routines privileges are required in order to use mtaSena Enqueuing messages requires privileges sufficient to create open read from and write to the MTA message queue directories On UNIX this is accomplished by having your executable program owned and run by the MTA account or alternatively owned by the MTA and have the setuid attribute set In order to submit mail under a user name that differs from that of the calling process privileges are required On UNIX platforms the process must have the same real UID as either the root or Messaging Server account In some applications it is important to keep strict control over when privileges are enabled and disabled To this end the MTA PRIV ENABLE PROC and MTA PRIV DISABLE PROC item codes may be used to specify the addresses of two procedures to call immediately prior to and immediately after enqueuing a message This allows the required privileges to be enabled only when they are needed that is when the message is enqueued and to remain disabled at all other times The mtasend routine does not use a condition handler so if a fatal error occurs while enqueuing a message it is up to the calling program to trap the error and if necessary disable any privileges that should be disabled These procedures if specified should accept no arguments and return no function result return value
77. A HDR TO Specify a header only To address that is an inactive recipient which should only appear in the message s header The item address and item length fields specify the address and length of a string containing a To address The length of the address may not exceed ALFA SIZE bytes MTA HDRMSG FILE Specify the name of an input file containing both the message header and message body The content of the file represents an RFC 2822 formatted message with at least one blank line separating the RFC 2822 header from the message body The mtaSend routine uses the header lines from the input file to form an initial message header This initial header is then modified as necessary The item address and item length fields specify the address and length of a text string containing the input file s name The length of the string may not exceed ALFA SIZE bytes Item Codes 260 Messaging Server 6 2005Q1 MTA Developer s Reference Item Codes MTA HDRMSG PROC Specify the address of a procedure that will return one line at a time each line of an RFC 822 formatted message The RFC 822 header must come first followed by at least one blank line followed by the message body The item address field specifies the address of the procedure to invoke The calling format that must be used by the procedure is given in Message Headers and Content on page 240 MTA IGNORE ERRORS Send the message as long as at least one To address was o
78. A HDR TO None The address is not an active transport address do not add it to the envelope recipient list The address should however be added to a To header line MTA NOTIFY FLAGS size t nflags Delivery status notification flags specific to this envelope recipient address A value specified with this item code overrides any setting made for the message itself when the enqueue context was created It also overrides any value inherited from a dequeue context Note that this item code has no effect when HDR BCC MTA HDR CC or MTA HDR TOis specified notification flags only apply to active transport addresses For further details see the description of this item code for mtaEnqueueStart on page 193 This item code must be followed by one additional call argument the address of an integer to receive the setting of the delivery status notification flags MTA ORCPT TO const char orcpt Specify the original envelope recipient address in RFC 1891 original recipient address format for example rfc822 sue siroe com for sue siroe com size_t orcpt_len This item code must be followed by two additional arguments 1 The pointer to the original recipient address 2 The length in bytes of that address If a value of zero is supplied for the length then the address string must be NULL terminated 204 Messaging Server 6 2005Q1 MTA Developer s Reference mtaEnqueueTo Description Provide the address of a string po
79. A ORDER Call made out of sequence The call was made either before the recipient list has been exhausted with mtaDequeueRecipientNext or after the message had been dequeued or deferred with mtaDequeueMessageFinish MTA THREAD The MTA SDK detected simultaneous use of the dequeue context by two different threads Example There are three code examples each showing variations on deferring a message The following code fragment shows how to use this routine to defer processing of a message until a later time by calling the routine with the MTA ABORT item code mtaDequeueMessageFinish dq ctx MTA ABORT 0 The following code fragment shows how to use this routine to defer processing of a message and setting the disposition mtaDequeueMessageFinish dq ctx MTA DISP MTA DISP DEFERRED 0 The following code fragment shows how to use this routine to defer processing of a message with a text string explaining the reason for the deferral mtaDequeueMessageFinish dq ctx MTA ABORT MTA_REASON Temporary network error 0 0 mtaDequeueRecipientDisposition Specify the delivery status disposition of an envelope recipient address Chapter 6 MTA SDK Reference 165 mtaDequeueRecipientDisposition Syntax int mtaDequeueRecipientDisposition mta dq t dq ctx const char env to size t env to len size t disposition int item code Arguments Arguments Description dq ctx A dequeue context create
80. A subroutine libraries can produce diagnostic output as can the MTA SDK itself This output when enabled is directed to stdout When a channel program is run by the Job Controller stdout is directed to the channel s debug log file Use this diagnostic output when developing programs NOTE mtaDebug may also be used in production programs however caution should be used as it can be quite verbose and voluminuous thereby degrading performance and consuming disk space As described in the following table item codes are used to select specific types of diagnostic output Additional Arguments Description ECODE None Enable diagnostic output from the low level MIME decoding routines This might be helpful when trying to understand MIME conversions that occur either when enqueuing messages and the destination channel is configured to invoke MIME conversions for example marked with channel keywords such a thurman or inner or when using mtaDecodeMessage Chapter 6 MTA SDK Reference 133 Item Codes MTA DEBUG DI Description Enable diagnostic output from low level queue processing routines Use this when trying to understand issues around reading and processing of queued message files This will not help diagnose the selection of queued messages which is handled by the Job Controller Enabling this diagnostic output is the equivalent of setting DEQUEUE DEBUG 1 in the option file option dat Enables ou
81. ADS attemtps MTA JBC MAX ATTEMPTS LOOP while threads running threads max Go to DONE if a shut down has been requested pending_messages Ask the Job Controller how many messsages there are to be processed If there are no pending messages then consider what to do next if pending_messages 0 Continue to wait if attempts lt 0 go to DONE Decrement attempts and wait attempts attempts 1 go to SLEEP Reset the attempts counter attempts MTA_JBC_MAX_ATTEMPTS threads_needed Ask the Job Controller how many processing threads are needed Cannot run more then threads_max threads per process if threads_needed gt threads_max threads_needed threads_max hreads if needed hreads_running Create additional t if threads_needed gt t Create threads_needed threads_running more threads threads_running threads_needed SLEEP Chapter 4 Dequeuing Messages 81 Multiple Calls to mtaDequeueStart Sleep for MTA JBC RETRY INTERVAL seconds a shut down request will cancel the sleep go to LOOP DONE Wait up to MTA THREAD WAIT TIMEOUT seconds for all processing threads to exit Return to the caller of mtaDequeueStart Multiple Calls to mtaDequeueStart A channel program can call mtaDequeueStart multiple times either sequentially or in parallel In the latter case the program would need to create threads so as to effect multiple s
82. Callable Send facility will be logged when the channels involved are marked with the logging channel keyword Required Privileges Use of the MTA SDK often requires access rights to the MTA message queues and configuration data Indeed were such rights not required then any user capable of logging in to the operating system of the machine running Messaging Server could read messages out of the MTA message queues and send fraudulent mail messages Consequently any programs using the MTA SDK need read access to the MTA configuration possibly including files with credentials required to bind to either the Job Controller or an LDAP server or both Additionally programs that will enqueue messages to the MTA need write access to the MTA message queues Programs that will dequeue messages from the MTA need read write and delete access to the MTA message queues To facilitate this access site developed programs that will enqueue or dequeue messages should be owned and run by the account used for Messaging Server The programs do not need to run as a superuser with root access in order to enqueue or dequeue mail to the MTA However it is safe to allow them to do so if needed for concerns outside the scope of Messaging Server For instance if the program will be performing other functions requiring system access rights it needs to run as a superuser with root access Chapter 2 MTA SDK Programming Considerations 3 Compiling and Link
83. DK 34 configuration access rights 33 refreshing stale 39 contexts defined 22 dequeue 25 26 enqueue 24 global 64 threads 22 D date 131 debugging enabling 133 272 Messaging Server 6 2005Q1 MTA Developer s Reference Section E envelope 23 envelope fields 47 189 error reporting 185 example 24 finishing 187 from address 193 headers 23 intermediate channel sample program 73 intermediate channels 46 intermediate processing channels 71 recipients 200 sample program 43 starting 193 threads 24 to 200 writing 206 209 enqueuing routines mtaEnqueueCopyMessage 183 mtaEnqueueError 185 mtaEnqueueFinish 187 mtaEnqueuelnfo 189 mtaEnqueueStart 193 mtaEnqueueTo 200 mtaEnqueueWrite 206 mtaEnqueueWriteLine 209 envelope fields for enqueuing 47 message component 23 recipient disposition 52 error codes retrieving 38 error handling routines mtaErrno 211 mtaStrError 230 examples complex dequeuing program 63 intermediate processing channel 73 pseudo code thread creation loop 81 simple decoding program 89 simple dequeuing program 56 simple enqueuing program 43 simple virus scanner program 95 executing programs 31 34 Index 273 intermediate channels 71 Job Controller 26 processing routine tasks 52 pseudo code thread creation loop 81 reading 160 recipient disposition 165 recipients 169 removing messages 25 re reading 171 rewinding 171 sample program 56 starting 172 threads 26 dequeuing routines mtaDequeuelnfo 1
84. E E Error Handling ore ees InitializauOb A A Logging and Diagnostics MIME Parsing and Decoding 7777 77 1156611608 Option File Processing socie eee esses MTA SDK mtaAccountingLogClose ooooooommmo mtaAddressFinish o oooooomoomoo mtaAddressGetN 2 24 065 ies ds mtaAddressParse 00 0 cece cece eens mtaAddressToChannel mitaBlockSize 22 2 cse sereo ges mtaChannelGetName 3 01105 1 61 18 8 tita late TIG otc cess e omae toner RAD eve te I DR Ee aes mtabebug 2e mtaDecodeMessage 2 Inspection Routme 4 eee Output ROUEN es seek ernas Dequeue Context omicoscioa diri Caller Supplied Input Routine Enquetie Context i sce eee es Caller Supplied Output Routine Decode Context Queries Bem Codes i Leber f ee Ee mtaDecodeMessagelnfoInt mtaDecodeMessagelnfoParams mtaDecodeMessagelnfoString mtaDecodeMessagePartCopy mtaDecodeMessagePartDelete mtaDequeuelnfo oprise yes cee eO nha cional ia mtaDequeueMessageFinish mtaDequeueRecipientDisposition nitabequeueleciptentNext imita mtabDequeueRewind oesi ose ccs eee es Other Considerations for mtaDequeueStart Multiple Calls to m
85. Example 5 2 that follows shows how to use the mtabecodeMessage routine to write an intermediate processing channel that converts messages with formats other than MIME for example UUENCODE content to MIME output It then decodes the MIME message scanning it for potentially harmful attachments In this example an attachment is any message part Any harmful attachments are removed from the message after which it is re enqueued for delivery The list of harmful MIME media types and file name extensions is read from a channel option file An example option file for the channel is shown in Example Option File on page 106 In this example the MIME Content type and Content disposition header lines are used to detect potentially harmful message attachments such as executable files This example could be extended to also scan the content of the attachments possibly passing the contents to a virus scanner Further the example could be modified to return as undeliverable any messages containing harmful attachments NOTE To configure the MTA to run this channel see Running Your Enqueue and Dequeue Programs on page 31 The PMDF CHANNEL OPTION environment variable must give the absolute file path to the channel s option file Also for a discussion on configuring special rewrite rules for re enqueuing dequeued mail see Preventing Mail Loops when Re enqueuing Mail on page 37 For the output generated by this sample program see Decoding MIME M
86. INARY on page 261 MTA MODE TEXT on page 262 250 Messaging Server 6 2005Q1 MTA Developer s Reference mtaSend Syntax MTA MSG FILE on page 262 MTA MSG PROC on page 262 MTA NOBLANK on page 262 MTA NOIGNORE ERRORS on page 263 MTA PRIV DISABLE PROC on page 263 MTA PRIV ENABLE PROC on page 263 MTA SUBADDRESS on page 263 MTA SUBJECT on page 264 MTA TO on page 264 MTA USER on page 264 mtaSend Syntax Syntax int mtaSend mta item list t item list Arguments item list The mtaSend routine takes only one argument item list which is a pointer to an array of item descriptors Each item descriptor specifies an action to be taken and provides the information needed to perform that action The list of item descriptors is terminated with an entry containing the MTA END LIST 0 item code Each item descriptor has the following C style structure declaration struct int item code const void item address int item length int item status const char item smessage mta item list t Chapter8 mtaSend Routine Specification 251 Item Descriptor Fields item code Integer item code specifying an action to be taken by mtasend The include file described in Chapter 1 MTA SDK Concepts and Overview defines these codes Each item code is described later in this chapter starting at Item Codes on page 253 item address The caller
87. ION ET SA REPRODUCTION SONT INTERDITES SANS L AUTORISATION EXPRESSE ECRITE ET PREALABLE DE SUN MICROSYSTEMS INC Cette distribution peut comprendre des composants d velopp s par des tierces parties Des parties de ce produit peuvent tre d riv es des syst mes Berkeley BSD licenci s par l Universit de Californie UNIX est une marque d pos e aux Etats Unis et dans d autres pays et licenci e exclusivement par X Open Company Ltd Sun Sun Microsystems le logo Sun Java Solaris JDK Java Naming and Directory Interface JavaMail JavaHelp J2SE iPlanet le logo Duke le logo Java Coffee Cup le logo Solaris le logo SunTone Certified et le logo Sun tm ONE sont des marques de fabrique ou des marques d pos es de Sun Microsystems Inc aux Etats Unis et dans d autres pays Toutes les marques SPARC sont utilis es sous licence et sont des marques de fabrique ou des marques d pos es de SPARC International Inc aux Etats Unis et dans d autres pays Les produits portant les marques SPARC sont bas s sur une architecture d velopp e par Sun Microsystems Inc Legato le logo Legato et Legato NetWorker sont des marques de fabrique ou des marques d pos es de Legato Systems Inc Le logo Netscape Communications Corp est une marque de fabrique ou une marque d pos e de Netscape Communications Corporation L interface d utilisation graphique OPEN LOOK et Sun TM a t d velopp e par Sun Microsystems Inc pour ses utilisateurs et licenci
88. Info Or mtaDequeueInfo routines The former returns the channel name the SDK will use when no other name is explicitly specified through code The latter two return the name specifically being used with a given enqueue or dequeue context NOTE The SDK only reads the PMbF CHANNEL environment variable once per program invocation As such running code cannot expect to change its channel name by changing the value of the environment variable Messaging Server 6 2005Q1 MTA Developer s Reference 32 Debugging Programs and Logging Diagnostics Debugging Programs and Logging Diagnostics The SDK has diagnostic facilities that may help in tracking down unusual behavior Enable SDK diagnostics in one of two ways either when the SDK is initialized with mtaInit or afterwards with mtaDebug The following table lists the diagnostics types that may be enabled through either routine Diagnostic Type Description MTA DEBUG SDK Provide diagnostics whenever the SDK returns an error status MTA DEBUG DEQUEUE Provide diagnostics from the MTA low level dequeue library MTA DEBUG ENQUEUE Provide diagnostics from the MTA low level enqueue library MTA DEBUG OS Provide diagnostics from the MTA low level operating system dependent library All diagnostic output is written to stdout In the case of a channel program this is typically the channel s debug file Message enqueue and dequeue activities performed through the MTA SDK and
89. It will be as if the MTA DISP DEFFERED disposition was set for all of the message s recipients This will be the case even if the processing routine returns a success status code of zero In the event that the processing routine needs to abort processing of a single message it should call mtabequeueMessageFinish with the MTA ABORT flag set If the processing routine returns with a status code of MTA ABORT then the execution thread that called the processing routine will perform an orderly exit Consequently the program can prematurely terminate itself in a graceful fashion by causing its processing routine to begin returning the MTA ABORT status code each time it is called The process message Routine This caller supplied routine is invoked by the processing threads to do the actual processing of the messages The following code example shows the required syntax for a process message routine int process message void ctx2 void ctx1 mta dq t dq ctx const char env from int env from len Messaging Server 6 2005Q1 MTA Developer s Reference 54 The process message Routine The following table lists the required arguments for a process message routine and gives a description of each Arguments Description ctx2 A writable pointer that the process message routine can use to store a pointer to a per thread context See the description that follows for further details ctxl The caller supplied pri
90. K diagnostics with mt aDebug Insufficient virtual memory cannot perform the requested operation This error code is not presently used by the MTA SDK In general it is used to indicate that the requested operation was completed by doing nothing for example a message enqueued to zero envelope recipients is simply deleted The specified channel name does not exist in the MTA configuration The channel name may have been specified explicitly with a supplied call argument or implicitly with the PMDF_CHANNEL environment variable The MTA configuration lacks the necessary information to route the specified envelope recipient address This error typically comes up when an unrecognized top level domain name is used As such this usually indicates a syntactically valid recipient address which specifies an invalid top level domain name for example sue siroe siroe Other addressing errors including syntax errors may elicit this status code Numeric Value 5 P Return Code MTA_FCREATE MTA_FIO MTA_OPEN MTA_NETWORK TA_NOSUCHCHAN TA_NOSUCHHOST MTA_NO TA_NOMEM TA_NOOP 266 Messaging Server 6 2005Q1 MTA Developer s Reference 207 Description An invalid item code was supplied Either the supplied item code value does not represent a known item code or it is not an item code supported by the called routine Routine called out of order For example an attempt to read the text
91. MSG FILE send header txt MTA END LIST 0 mtaSend item list 244 Messaging Server 6 2005Q1 MTA Developer s Reference Examples of Using mtaSend Example 2 Input File Subject MTA SDK callable Send example To root sesta com MIME version 1 0 Content type TEXT PLAIN CHARSET US ASCII Content transfer encoding 7BIT Comments Ignore this message it s just a test This is a test of the emergency broadcasting system 1234567890123456789012345678901234567890123456789012345678901234 5678901234567890 0000000001111111111222222222233333333334444444444555555555566666 6666677777777778 Example 2 Output Date 04 Jan 2003 22 42 25 0800 PST From system sesta com Subject MTA SDK callable Send example To system sesta com Message id 01GPKFNPUQF89LVIWXGsesta com MIME version 1 0 Content type TEXT PLAIN CHARSET US ASCII Content transfer encoding 7BIT Comments Ignore this message it s just a test This is a test of the emergency broadcasting system 1234567890123456789012345678901234567890123456789012345678901234 5678901234567890 0000000001111111111222222222233333333334444444444555555555566666 6666677777777778 Example 3 Sending a Message to Multiple Recipients The program given in Code Example 7 3 demonstrates the following points Sending a message to multiple recipients e Obtaining the status legal illegal of each envelope recipient address that is active transpor
92. MTA master channel For this case queued messages are gatewayed to another mail system A dequeue context is used for the input source and an output destination is often not needed the inspection routine usually suffices Channels of this sort are common place when interfacing Messaging Server to systems that do not support MIME and for which conversion of MIME formatted messages to other formats is required for example X 400 and SMS Acommand line utility to parse a message For this case a caller supplied input routine is used No output destination is needed an inspection routine usually suffices The Input Source The message to be decoded is provided as either a dequeue context or a caller supplied routine Dequeue Context When using a dequeue context you must observe the following 1 Pass the dequeue context from mtaDecodeStart to mtaDecodeMessage along with the MTA DECODE DQ item code 2 The recipient list of the message being dequeued must have already been read by mtaDequeueRecipientNext before calling mtaDecodeMessage 3 mtaDequeueMessageFinish must not yet have been called for the dequeue context After using a dequeue context with mt aDecodeMessage further calls to mtaDequeueRecipientNext can t be made Calls to mtaDequeueLineNext can only be performed after a call to mtaDequeueRewind Caller Supplied Input Routine To use a caller supplied input routine pass the address of the i
93. MTA TERM LFCR MTA TERM NONE 144 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDecodeMessagelnfolnt Return Values Return Values Description 0 Successful normal completion MTA BADARGS Two conditions cause this error 1 A NULL value was supplied for input output when output type is non zero or a required argument to an item code 2 Aninvalid value supplied for either input type oroutput type MTA FOPEN Unable to initialize the MTA SDK Unable to read one or more configuration files For further information issue the following command imsimta text rewrite MTA NO Can be sent for one of three reasons 1 Error parsing the supplied message 2 An error reading from the queued message file when MTA DECODE DQis supplied for input type 3 Unable to initialize the MTA SDK In this case issue the command imsimta test rewrite MTA NOMEM Insufficient virtual memory MTA NOSUCHITEM An invalid item code was specified Example For examples of using mtaDecodeMessage see Decoding MIME Messages on page 89 and Decoding MIME Messages Complex Example on page 96 mtaDecodeMessagelInfoInt Obtain integer valued information relating to the current message part Chapter 6 MTA SDK Reference 145 mtaDecodeMessagelnfolnt Syntax int mtaDecodeMessageInfoInt mta decode t dctx int item Arguments Arguments Description dctx A decode context created by mtaMessageDecode item Item i
94. Messages Complex Example on page 96 mtaEnqueueTo Add an envelope recipient to a message being submitted 200 Messaging Server 6 2005Q1 MTA Developer s Reference mtaEnqueueTo Syntax int mtaEnqueueTo mta nq t ctx const char to adr size t to adr len int item code Arguments Arguments Description nq ctx Pointer to an enqueue context created with mtaEnqueueStart to adr An address to add to the message being enqueued The address must be compliant with RFC 2822 When used as an envelope address the MTA will reduce it to an RFC 2821 compliant transport address If a value of zero is passed for to adr len the address string must be NULL terminated The length of this string not including any NULL terminator may not exceed ALFA SIZE bytes to adr len The length in bytes not including any NULL terminator of the address supplied with to adr If a value of zero is passed for this argument then the address string must be NULL terminated item code An optional list of item codes See the description section below for a list of item codes The list must be terminated with an integer argument with value 0 Description After initiating a message enqueue operation with mtaEnqueueStart the envelope recipient list for the message must to be constructed This list is the actual list of recipients to which the message is to be delivered A message must have at least one envelope recipient address otherwise
95. O option for mtaEnqueueTo is specified so that the address is to be added to the new message s envelope only It should not also be added to the message s RFC 822 header The new message s header will be a copy of the header of the message being dequeued This copy is performed at the code location marked by comment 12 9 Each recipient is marked as delivered with mt aDequeueRecipientDisposition 10 In the event of an error returned from either mtaEnqueueTo or mtaDequeueRecipientDisposition or an unexpected error return from mtaDequeueRecipientNext the ongoing enqueue is cancelled and the processing of the current message is deferred 11 Each line of the current message is read and then copied to the new message being enqueued This copying continues until a blank line is read from the current message A blank line signifies the end of the RFC 822 message header and the start of the RFC 822 message content 12 The code here needs to determine why it exited the read loop because of an error or because the transition from the message s header to body was detected 13 The remainder of the current message is read line by line and copied to the new message being enqueued However the line enqueued is first transformed using the rot13 transformation The per thread context my_ctx_2 is used to hold an output buffer used by the rot13str routine 14 The enqueue of the new message is finished If that step succeeds then
96. Reference Glossary Refer to the Java Enterprise System Glossary http docs sun com doc 816 6873 for a complete list of terms that are used in this documentation set 269 270 Messaging Server 6 2005001 MTA Developer s Reference Section A Index BIGALFA_SIZE 1024 defined 27 block size 126 body 24 0 callable send access privileges 241 basic steps for sending a message 237 bcc 239 cc 239 compiling and linking programs 242 envelope addresses 238 example sending a message to multiple recipients 245 sending a simple message 243 specifying an initial message header 244 using an input procedure to generate the message body 247 header from addresses 238 message content body 240 message header 240 to 239 caller supplied routines decode inspect 88 decode read 87 decode write 94 process done 62 Index 271 A aborting dequeuing messages 54 162 enqueue 187 message submission enqueue 42 access rights callable send 241 configuration 33 accessing queued messages 49 address parsing routines mtaAddressFinish 118 mtaAddressGetN 118 mtaAddressParse 121 addresses bcc 202 cc 202 from 193 mapping to channel 123 parsing 118 121 postmaster 227 to 205 ALFA SIZE 256 defined 27 aliases inhibiting 196 B bcc addresses 202 239 errno 1 SDK diagnostic facility 33 writing debug output 215 217 decode context 94 decode inspect routine 88 decode read routine 87 decode write r
97. Routine To assist in cleaning up state information for a thread callers can provide a routine pointed to by the process done argument The following code fragment shows the required syntax for a process done routine void process done void ctx2 void ctx1 The following table lists the arguments required for a process done routine and gives a description of each Required Arguments Description ctx2 The value of the last pointer stored by process message in the ct x2 call argument for this thread ctx1 The caller supplied private context passed as ctx1 to mtaDequeueStart The following code fragment demonstrates the type of actions taken by a process_done routine void process done ctx2 ctxl struct our_state_t state our_state_t ctx2 if state return Take steps to undo the state for example close any sockets or files j mtaDequeueStart 180 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDequeueStart Free the memory allocated by process message to store the state ES free state Thread Creation Loop While the processing threads are running the thread that invoked mtaDequeueStart executes a loop containing a brief pause that is a sleep request Each time the mtaDequeueStart thread awakens it communicates with the Job Controller to see if it should create more processing threads In addition the Job Contro
98. Syntax void mtaAccountingClose void Arguments None Chapter 6 MTA SDK Reference 7 Description Long running programs should periodically close the MTA accounting log file with this routine Interactive programs that use the MTA SDK should use the TA INTERACTIVE item code when initializing the SDK with mtaInit Return Values None Example None mtaAddressFinish mtaAddressFinish Dispose of an address context Syntax void mtaAddressFinish mta adr t adr ctx Arguments Argument Description adr ctx An address context created by a previous call to mtaAddressParse Description Address contexts created with mtaAddressParse must be disposed of by calling mtaAddressFinish Failure to do so will result in memory leaks Return Values None Example None mtaAddressGetN Extract an address from a list of parsed addresses 118 Messaging Server 6 2005Q1 MTA Developer s Reference mtaAddressGetN Syntax int mtaAddressGetN mta adr t adr ctx size t address index const char address size t address len int elements Arguments Arguments Description adr ctx An address context created by a previous call to mtaAddressParse address index Index of the address to retrieve It is an index into a list of addresses The first address has an index of 0 address Pointer to receive the selected address a pointer to a buffer within the address context The address will be NULL te
99. TA The only distinction the MTA SDK makes between these two cases occurs when the message s recipient addresses are specified For new messages being originated the recipient addresses should be added to both the message s header and its envelope For messages originated elsewhere the recipient addresses should only be added to the message s envelope For a discussion of messages originated elsewhere see Transferring Messages into the MTA on page 46 and Intermediate Processing Channels on page 46 When originating a new message it is easiest to use the MTA TO MTA CC and MTA BCC item codes with mtaEnqueueTo That tells the SDK to use the specified addresses as both the envelope recipient list and to put them into the message s header When using this approach do not specify any From To Cc Or Bcc header lines in the supplied message s header the SDK will add them automatically An example of using this approach is found in the section that follows A Simple Example of Enqueuing a Message The program shown in Code Example 3 1 demonstrates how to enqueue a simple Hello World message The originator address associated with the message is that of the MTA postmaster The recipient address can be specified on the invocation command line After the Messaging Server product is installed this program can be found in the following location Chapter 3 Enqueuing Messages 43 A Simple Example of Enqueuing a Message
100. To process queued messages a processing thread takes the following steps 1 The thread sets ctx2 to have the value NULL ctx2 NULL For information on the process_message arguments see The process_message Routine on page 54 Messaging Server 6 2005Q1 MTA Developer s Reference 60 Processing the Message Queue 2 The execution thread communicates with the Job Controller to obtain a message file to process If there are no more message files to process then go to Step 9 3 Forthe message file the execution thread creates a dequeue context that maintains the dequeue processing state for that message file 4 The execution thread then invokes the caller supplied process message routine passing to it the dequeue context created in Step 3 as shown in the example that follows istat process message amp ctx2 ctxl amp dq ctx env from env from len For information on the call arguments for process message see The process message Routine on page 54 5 The process message routine then attempts to process the message ultimately removing it from the channel s queue or leaving the message file for a later processing attempt 6 IfmtaDequeueMessageFinish was not called before process message returned then the queued message is deferred That is its underlying message file is left in the channel s queue and a later processing attempt is scheduled 7 The dequeue context is destroyed
101. a System Messaging Server 6 200402 built Mar 24 2003 id OHCH00301E7DOH00Gfrodo west wiroe com for sue sesta com Fri 28 Mar 2003 14 51 52 0800 PST Date Fri 28 Mar 2003 14 51 52 0800 PST From root frodo west siroe com Subject Testing To sue sesta com Message id 0HCH00303E6GO7008frodo west siroe com MIME version 1 0 Guvf vf n grfg zrffntr Thread Creation Loop in mtaDequeueStart After mcaDequeueStart performs any necessary initialization steps it then starts a loop whereby it communicates with the MTA Job Controller Based upon information from the Job Controller it then creates zero or more execution threads to process queued messages Messaging Server 6 2005Q1 MTA Developer s Reference 80 Thread Creation Loop in mtaDequeueStart While any execution threads are running the thread that invoked mtaDequeueStart the primal thread executes a loop containing a brief pause that is a sleep request Each time the primal thread awakens it communicates with the Job Controller to see if it should create more execution threads In addition the Job Controller itself has logic to determine if more threads are needed in the currently running channel program or if it should create additional processes to run the same channel program To demonstrate the following code example shows pseudo code of the mtaDequeueStart loop threads running 0 threads max MTA THREAD MAX THRE
102. a pointer to an opaque data structure called a context This mechanism allows for management of state information across calls to the SDK Use of the contexts allows multiple threads within a single program to make simultaneous calls to the same SDK routine The only limitation is that a single specific context may not be simultaneously used by different threads in calls to the SDK When such usage is detected in an SDK call an MTA THREAD error results In some cases these contexts are automatically created for you such as dequeue and decode contexts In all other cases for example for enqueue contexts you must make an explicit call to create them The calls that automatically create contexts also automatically dispose of them In all other cases a call must be made to explicitly dispose of a context It is important to dispose of contexts when you no longer need them as so doing releases resources such as virtual memory For more information on contexts see Threads and Enqueue Contexts on page 24 and Threads and Dequeue Contexts on page 26 Enqueuing Messages Messages are introduced to the MTA by enqueuing them Each enqueued message contains two required components the message envelope and the message header and may optionally contain a third component the message body The contents of the envelope and header must be provided by the program using the SDK For instructions on how to enqueue messages see Chapter 2 MTA SDK P
103. aSend using an input procedure to generate the message body 247 pseudo code thread creation loop 81 simple decoding program 89 simple dequeuing program 56 simple enqueuing program 43 simple virus scanner program 95 SDK routines address parsing mtaAddressFinish 112 118 mtaAddressGetN 112 118 mtaAddressParse 112 121 dequeuing mtaDequeuelnfo 112 156 mtaDequeueLineNext 160 mtaDequeueMessageFinish 112 162 mtaDequeueRecipientDisposition 165 mtaDequeueRecipientNext 112 169 mtaDequeueRewind 112 171 mtaDequeueStart 112 172 mtaDequeueThreadId 182 enqueuing mtaEnqueueCopyMessage 113 183 mtaEnqueueError 185 mtaEnqueueFinish 113 187 mtaEnqueuelnfo 113 189 Section P integer values 220 reading an option file 222 starting 222 string values 225 option processing routines mtaOptionFinish 218 mtaOptionFloat 219 mtaOptionInt 220 mtaOptionStart 222 mtaOptionString 225 output routine decode_write 94 output channel program 38 P persistent programs considerations 38 log file considerations 39 refreshing 39 postmaster address 227 privileges required 33 241 process done routine 62 process message routine 54 processing messages Job Controller 26 queued 60 processing routine tasks 52 production running programs 32 programming considerations 38 R recipient disposition deferred 52 delivered 52 dequeued messages 52 failed 53 mtaDequeueRecipientDisposition 165 relayed 53 relayed foreign 53 returned 53
104. additional argument the address of a size t to store the setting s value in Return the delivery status notification flags set for the entire message when the enqueue was started The returned value is a bit map constructed using the MTA NOTIFY constants defined in mtasdk h If no setting was effected with mtaEnqueueStart then the returned value will be the MTA default of MTA NOTIFY DELAY MTA NOTIFY FAILURE MTA NOTIFY CONTENT FULL This item code must be followed by one additional call argument the address of a size t to receive the setting of the delivery status notification flags mtaEnqueuelnfo Item Codes Continued Additional Arguments MTA EXPAND LIMIT size t value MTA FRAGMENT BLOCKS size t value MTA FRAGMENT LINES size t value MTA NOTIFY FLAGS size t nflags 192 Messaging Server 6 2005Q1 MTA Developer s Reference mtaEnqueueStart Return Values Return Values Description 0 Normal successful completion MTA_BADARGS This value is returned for one of the following reasons 1 A NULL value was supplied for the ng ctx call argument 2 An invalid enqueue context was supplied for nq ctx 3 Arequired argument to an item code was NULL MTA NOSUCHITEM An invalid item code was specified MTA THREAD Simultaneous use of the enqueue context by two different threads was detected Example The following code fragment obtains the name of the channel used as the source channel for the
105. ae E Reade ee LO OBL RIA ESI ad Ea Lus 222 iii Dese Pese A E da E DE REA Ed PORE de ds 225 ita Postmaster Address thee A a oe SR RERO CH QNID a ates 227 mitaStackSizZe GSES Se FEA Ee eae 44 eee ede ee 229 iila BERE oci hee EM et SR atur cet de cta feet tote hectare dito tid 230 MtaUMiquesMing ii ex Heady Ge nid ohne ter eetad sated wa Gore d dude eu tates 230 o A A E E O R AE E EER 231 Mita Version MIROE is d RR Rp E ed we A eee 232 gita Version REVISION 222 ox ce ERRARE ON eee Se AAR a EA p a act EE a 232 Part Il Callable Send ete eel edule oe n er uod eoo cd uon 235 Chapter 7 Using Callable Send mtaSend 237 pending a Message econcevedeec e e per rl RRERPIURDEHPSTUOPITHU OS RAN dd 237 Envelope and Header From Addresses 15 ke n c beers Eme be LORS 238 To Ce and Bec Addresses cociopiisnisaion ui d aa e v a IEEE a ede Pad 239 Message Headersand Content s ac 004 040 dee ue D ewe ea Re eae eee ae dees 240 Required Privileges iii rn eb RERO pie OR OS RR EA Ee Rd vided dapes 241 es Dispose seiss resia ar nek Ed ste toh Ooh nad aay ease P Pes RS bei 241 Compiling and Linking Programs iii e a a eves dead e wes err hl e Deis s 242 Contents 7 MITA CHANNEL coda Y Rubr eePE EET ERA MIA CRILENAME TH EU ECOL PRESE MTA CHLENAME NONE ien here E ES E DR epa CIYPE oeste ide Rhea aes odes MIA ENC BASBGA jogo rk ew a e
106. age The string must be NULL terminated if a value of zero is passed for 1en2 If only supplying a single string then pass a NULL value for this argument Description After a message s list of envelope recipient addresses has been supplied with mtaEnqueueTo the message itself must be supplied This is done by repeatedly calling mtaEnqueueWrite First the message s header should be supplied followed by a blank line followed by any message content Each line of message data must be terminated by a US ASCII line feed character 0x02 Each call to mtaEnqueueWrite can supply one or more bytes of the message s data Unlike mtaEnqueueWriteLine a single call to ntaEnqueueWrite does not necessarily correspond to a single complete line of message data it could correspond to a partial line a complete line multiple lines or even one or more complete lines plus a partial line This flexibility with mtaEnqueueWrite exists because it is up to the caller to supply the message line terminators Calling either mtaEnqueueWrite or mtaEnqueueWriteLine terminates the message s envelope recipient list Once either of these routines have been called mtaEnqueueTo can no longer be called for the same enqueue context Chapter 6 MTA SDK Reference 7 Return Values Return Values Description 0 Normal successful completion BADARGS This value is returned for one of the following reasons 1 A NULL value was supplied
107. agePartCopy 13 Using the configured channel options this routine determines if a message part s media type is in the list of harmful types 14 Using the configured channel options this routine determines if a filename appearing in the MIME header lines has an extension considered harmful 15 The 1oad options routine is used to load the channel s site configured options from a channel option file 16 The channel option file if any is opened and read by mta0ptionStart Since an explicit file path is not supplied the file path specified with the PMDF CHANNEL OPTION environment variable gives the name of the option file to read 17 After loading the channel s options the option file context is disposed of with a call to mtaOptionFinish Decoding MIME Messages Complex Example Output The example that follows shows the output generated by the MIME decoding program found in Code Example 5 2 on page 96 Received from sesta com by frodo siroe com Sun Java System Messaging Server Version 6 2004 Q2 built Apr 7 2003 id OHDEOOCOIBFK65008frodo siroe com for sue sesta com Tue 11 Apr 2003 13 03 29 0700 PDT Received from 129 153 12 22 129 153 12 22 by frodo siroe com Sun Java System Messaging Server 6 2004 Q2 built Apr 7 2003 with SMTP id lt 0HD70010230YDA00 frodo siroe com gt for sue sesta com Fri 11 Apr 2003 13 03 23 0700 PDT Messaging Server 6 2005Q1 MTA Developer s Reference 108
108. ain with mtaDecodeMessageInfoString TA DECODE CDISP PARAMS Parameter list to the Content disposition header line if any The parsed list is returned as a pointer to an option context For further information see mtaDecodeMessageInfoParams TA DECODE CSUBTYPE The content subtype specified with the part s Content type header line for example plain for text plain gif for image gif Defaults to plain when the part lacks a Content type header line Obtain with mtaDecodeMessageInfoString Message Code 94 Messaging Server 6 2005001 MTA Developer s Reference A Simple Virus Scanner Example Message Code Continued Description MTA DECODE CTYPE The major content type specified with the part s Content type header line for example text for text plain image for image gif Defaults to text when the part lacks a Content type header line Obtain with mtaDecodeMessageInfoString MTA DECODE CTYPE PARAMS Parameter list to the Content type header line if any The parsed list is returned as a pointer to an option context For further information see mtaDecodeMessageInfoParams MTA DECODE DTYPE Data type associated with this part Obtain with ntaDecodeMessageInfoInt MTA DECODE PART NUMBER Sequential part number for the current part The first message part is part 0 the second part is 1 the third part is 2 and so on Obtain with mtaDecodeMessageInfoInt A Simple Virus Scanner Example Code
109. al number of messages presented to a single processing thread This item code must be followed by one additional argument the number of messages for each processing thread MTA THREAD WAIT TIMEOUT size t seconds Once mt aDequeueMessage determines that there are no more messages to process it waits for all processing threads to complete their work and exit By default ntaDequeueMessage will wait no longer than 1800 seconds 30 minutes This item code must be followed by one additional argument the maximum number of seconds to wait Return Values Return Values Description 0 Normal successful completion MTA BADARGS This value is returned for one of following reasons 1 A NULL value was supplied for the dq ctx call argument 2 An invalid dequeue context was supplied for dq_ctx 3 ANULL value was specified for the process message routine 4 ANULL value was supplied for a required item code argument MTA FOPEN Unable to initialize the MTA SDK Unable to read one or more configuration files For further information issue the following command imsimta test rewrite Chapter 6 MTA SDK Reference 5 Description Error communicating with the Job Controller Unable to initialize the MTA SDK For further information issue the following command imsimta test rewrite Insufficient virtual memory Specified channel is not defined in the MTA configuration file If no channel was explicitly specified th
110. and other types of processing that occurs when a message is enqueued to the MTA Enabling this diagnostic output is equivalent to setting DEQUEUE DEBUG level in the MTA option file Enable diagnostic output from the low level operating system dependent routines used by the MTA SDK Use of this diagnostic output is helpful when diagnosing problems associated with creating opening writing or reading files Such problems typically arise when attempting to enqueue messages to the MTA a process that requires permissions to create and write messages in the MTA queues Enabling this diagnostic output is equivalent to setting 05 DEBUG 1 in the MTA option file Enable diagnostic output for the MTA SDK When this output is enabled diagnostic information will be output whenever the SDK returns an error result Specify a pointer to an item list array The item list array must be terminated with a final array entry with an item code value of zero For further information on item list usage see Item Codes and ltem Lists on page 28 Indicate that the SDK will be used by an interactive program In an interactive scenario the SDK manages some of the MTA resources differently than when running as a channel program For instance closing the MTA log file after every completed message submission or dequeue operation Additional Arguments None size t level None None mta item list t item list None mtalnit Item Code Cont
111. annel s queue and a subsequent processing attempt is scheduled The MTA_DISP_DEFERRED disposition is the only disposition that indicates a temporary processing problem Generation of delay notifications is handled by a special MTA process referred to as the return job Generation of delay notifications is not handled by mt aDequeueMessageFinish e If only a subset of the recipients have a disposition indicating a temporary processing problem then a new message is placed in the channel s queue This new message is identical to the current message being processed except that its envelope recipient list contains just those recipients whose disposition indicates a temporary processing problem The current message being processed is then removed from the channel s queue and any necessary notifications are sent for the recipients that had dispositions indicating successful processing or a permanent failure After mt aDequeueMessageFinish is called the dequeue context passed to it is no longer valid regardless of the status it returns When it returns an error status it also defers the message and all of its recipients for later processing This is done regardless of the disposition of the recipients Doing otherwise could potentially lead to lost mail Internet standards require that notifications concerning a message be directed to the message s envelope From address In addition the following two rules apply Automatically generat
112. are appended one after the other with no delimiters or separators This is the action selected with the MTA NOBLANK item code By specifying the MTA BLANK action mtaSend inserts a blank line between each input file This is especially useful when the first input file is to be treated as a source of header information and the second as the message body or part thereof This produces the requisite blank line between the message header and body The item address and item length fields are ignored for this item code Chapter8 mtaSend Routine Specification 253 MTA CC Specify a carbon copy Cc address The item address and item length fields specify the address and length of a string containing a Cc address The length of the address may not exceed ALFA SIZE bytes MTA CC is used to specify a Cc address that should appear in both the message s header and envelope MTA CHANNEL Specify the channel to act as when enqueuing the message If not specified then mail will be enqueued as though sent from the local 1 channel The item address and item length fields specify the address and length of a text string containing the name of the channel to act as The length of the string may not exceed CHANLENGTH bytes MTA CFILENAME When MTA CFILENAME is specified the name of the message input file will be included as a parameter in the MIME Content type header line This action when specified will hold for all subsequent input files un
113. artCopy Or mtaDecodeMessagePartDelete Therefore the only advantage to making an explicit call to mtaDecodeMessagePartCopy is that once that call is made the inspection routine will no longer be called for that particular message part Chapter 6 MTA SDK Reference 151 mtaDecodeMessagePartDelete Return Values Values Description 0 Normal successful completion MTA BADARGS A NULL value was supplied for the dctx call argument or an invalid decode context was supplied for dct x MTA NO Invalid call to this routine Either no output routine is being used or the call was made from the output routine itself Output errors encountered while attempting to write the output may also result in this error Example This routine is used in Decoding MIME Messages Complex Example on page 96 mtaDecodeMessagePartDelete Prevent a message part from being written or replace it with a text part Syntax int mtaDecodeMessagePartDelete mta decode t dctx int item code Arguments Arguments Description dctx A decode context created by mtaMessageDecode item code An optional list of item codes See the description section that follows for a list of item codes The list must be terminated with an integer argument with value 0 Description When an output routine is used in conjunction with mt aDecodeMessage the inspection routine may discard the current message part by calling this routine As an a
114. as specified Chapter 6 MTA SDK Reference 9 Return Values Return Values Description 0 Normal successful completion MTA STRTRUERR The supplied option name is too long Its length must not exceed ALFA SIZE bytes Example The following code example retrieves the value of an option named aspect ratio Before calling mtaoptionFloat a default value is set for the variable to receive the value of the option If the option was not specified in the option file then the variable will retain that default setting If the option was specified then the variable will assume the value set in the file ratio 7 mtaOptionFloat opt aspect ratio 0 amp ratio If itis important to know whether or not the option was specified then use mtaOptionString to test to see if the option was specified as shown in the following code example In this example when the routine returns the code determines that the option was specified by whether or not the value of the buflen variable has changed char buf l size t buflen buflen 1 mtaOptionString opt aspect ratio 0 buf amp buflen sizeof buf ratio specified buflen Oxffffffff 1 0 mtaOptionInt mtaOptionInt Interpret and return an option s value as an integer number 220 Messaging Server 6 2005Q1 MTA Developer s Reference mtaOptionInt Syntax int mtaOptionInt mta opt t opt_ctx const char name size t
115. atus code then repeat this cycle starting at Step 2 9 The caller supplied process done routine is called for example process done amp ctx2 ctxl For a description of the process done routine see process done Routine on page 180 10 The thread exits process message Routine This caller supplied routine is invoked by the processing threads to do the actual processing of the messages The following code fragment shows the required syntax for a process message routine int process message void etx2 void ctxl mta dq t dq ctx const char env from int env from len mtaDequeueStart 178 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDequeueStart The following table lists the required arguments for a process_message routine and gives a description of each Arguments Description ctx2 A writable pointer that the process_message routine can use to store a pointer to a per thread context See the description that follows for further details ctxl The caller supplied private context passed as ct x1 to mtaDequeueStart dq_ctx A dequeue context created by mt aDequeueStart and representing the message to be processed by this invocation of the process_message routine env_from A pointer to the envelope From address for the message to be processed Since Internet messages are allowed to have zero length envelope From addresses this address can have zero length The address wil
116. aults apply and imply that the content is text plain using the US ASCII character set Regardless of the value of the Content transfer encoding header line the content presented will no longer be encoded Inthe case of a multipart message the outermost header is not presented However it may be inspected by means of an output routine see Ihe Output Destination on page 93 A Simple Decoding Example This sample program found in Code Example 5 1 decodes a MIME formatted message using mtaDecodeMessage This is not a channel program The actual message to be decoded is compiled into the program rather than being drawn from a channel queue After the Messaging Server product is installed these programs can be found in the following location msg server base examples mtasdk Some lines of code are immediately preceded by a comment of the format See explanatory comment N where N is a number The numbers are links to some corresponding explanatory text in the section that follows this code see Explanatory Text for Numbered Comments on page 92 For the sample output generated by this program see MIME Message Decoding Simple Example Output on page 93 Code Example 5 1 Decoding MIME Messages decode simple c i Decode a multipart MIME message include lt stdio h gt include lt string h gt include mtasdk h Inline data for a sample message to decode See explanatory comment 1
117. ber of the MTA SDK Routine Name Continued mtaChannelGetName mtaChannelToHost mt aDateTime taPostmasterAddress El mtaStackSize El taUniqueString taVersionMajor El mtaVersionMinor mtaVersionRevision Option File Processing The following table lists the routines used to process option files and gives a brief description of them Routine Name Description taOptionStart Open and read a channel option file taOptionInt Obtain the value associated with an integer valued option taOptionFloat Obtain the value associated with a real valued option taOptionString Obtain the value associated with a string valued option taOptionFinish Dispose of an option file context Chapter 6 MTA SDK Reference 115 3 El 3 El 0 3 0 MTA SDK Routines MTA SDK Routines This section describes each MTA SDK routine including its syntax arguments and return values and gives a description of the routine The following table lists the routines in alphabetical order as they are found in this section Routine Name and Page mtaAccountingLogClose on page 117 mtaAddressFinish on page 118 mtaAddressGetN on page 118 mtaAddressParse on page 121 mtaAddressToChannel on page 123 mtaBlockSize on page 126 mtaChannelGetName on page 127 mtaChannelToHost on page 129 mtaDateTime on page 131 mtaDebug on page 133 mtaDecodeMessage on page 13
118. bject in RFC 1891 and may not have a length exceeding 100 bytes The value specified with this item code will override any value implicitly specified with the DO CONTEXT item code If no value is supplied either explicitly or implicitly then the MTA will generate a unique envelope ID for the message This item code must be followed by two additional call arguments 1 The address of the envelope ID string 2 The length in bytes of that string If a value of zero is supplied for the length then the string must be NULL terminated If the message has more envelope recipients than the specified limit then processing of the recipient list that is alias expansion will be deferred This deferral is performed by enqueuing the message to the reprocess channel At a later time and running in a separate process the reprocess channel will complete the processing of the envelope recipient list This item code must be followed by one additional argument the limit to impose By default no limit is imposed A large enqueued message may automatically be fragmented into several smaller messages using MIME s message partial content type At the destination MTA system these smaller messages may automatically be re assembled back into one single message The MTA FRAGMENT BLOCKS item code allows specification of a size threshold for which messages larger than the threshold will automatically be fragmented The limit specified is measured
119. bles one for each of the following logical groups of commands e Address Parsing on page 112 e Dequeue on page 112 e Enqueue on page 113 e Error Handling on page 113 e nitialization on page 3 Logging and Diagnostics on page 114 e MIME Parsing and Decoding on page 114 Miscellaneous on page 114 111 Summary of SDK Routines e Option File Processing on page 115 Each table lists the routines that comprise the group and gives a brief description of each Address Parsing Address parsing routines are used to parse and extract message addresses Routine Name Description mtaAddressFinish Dispose of an address context mtaAddressGetN Extract the Nth individual address from a list of parsed addresses mtaAddressParse Parse a list of addresses producing an address context Dequeue Dequeue routines are used for dequeuing messages Routine Name Description mt aDequeuelnfo Obtain information about a queued message mt aDequeueLineNext Obtain the next message line from a queued message mtaDequeueMessageFinish Complete or cancel a message dequeue mtaDequeueRecipientDisposit Set the disposition of a recipient address ion mt aDequeueRecipientNext Obtain the next recipient address from a queued message mt aDequeueRewind Move the read point for a queued message back to the start of its outermost header mtaDequeueStart Begin processing queued messages m
120. bytes channel option values will never exceed a length of BIGALFA SIZE bytes and envelope addresses will never exceed a length of ALFA SIZE bytes Value in Symbolic Names Bytes Typical Usage ALFA SIZE 256 Upper limit on the length of an address BIGALFA SIZE 1024 Upper limit on the length of message line and channel option value CHANLENGTH 32 Upper limit on the length of a channel name Chapter 1 MTA SDK Concepts and Overview 27 Item Codes and Item Lists Item Codes and ltem Lists A number of the MTA SDK routines accept a variable length list of item code arguments For instance mtaInit has the call syntax int mtaInit int item code That is to say it accepts one or more integer valued call arguments These call arguments are referred to as an item code list or more simply an item list Each item list must be terminated by a call argument with the value 0 As such the call syntax for mtaInit can be expressed as int mtaInit int item code 0 There can be zero or more item codes with non zero values which must then be followed by an item code with the value zero In the MTA SDK item lists serve two purposes First they allow code using the SDK to specify optional behaviors and actions to the SDK Second they provide an extension mechanism for future versions of the SDK to extend the functionality of routines through the introduction of new item codes However there is a drawback to the use of
121. c static int is bad mime type our options t options mta decode t Length of bft string size t bft len our options t Forward declarations static void error exit int ires Messaging Server 6 2005Q1 MTA Developer s Reference Code Example 5 2 96 A Simple Virus Scanner Example 97 Code Example 5 2 Decoding MIME Messages Complex Example Continued static mta dq process message t process message static mta decode read t decode read static mta decode inspect t decode inspect main Initialize the MTA SDK load our options and then start the message processing loop zy int main int ires our_options_t options Initialize the MTA SDK See explanatory comment 1 if ires mtaInit 0 error exit ires Unable to initialize the MTA SDK Load our channel options See explanatory comment 2 if ires load options amp options error exit ires Unable to load our channel options Now process the queued messages Be sure to indicate a thread stack size sufficient to accomodate message enqueue processing See explanatory comment 3 if ires mtaDequeueStart void amp options process message NULL 0 error exit ires Error during dequeue processing All done xf mtaDone return 0 process message This routine is called by mtaDequeueStart to process each queued bs message We don t
122. c procedure until a negative value is returned by the procedure Chapter 7 Using Callable Send mtaSend 247 Examples of Using mtaSend Code Example 7 4 Using an Input Procedure to Generate the Message Body send input c Demonstrate the use of MTA MSG PROC include lt stdio h gt include stdlib h include lt string h gt include mtasdk h ifdef _WIN32 typedef long ssize_t endif Push an entry onto the item list define ITEM item adr item list index item code item item list index item address adr item list index item length 0 item list index item status 0 item list indext item smessage NULL Ssize t msg proc const char bufadr static char buf 1024 if bufadr return 2 Call error abort printf input if fgets buf sizeof buf stdin bufadr buf buflen strlen buf if buf buflen 1 buflen 1 return buflen else return 1 EOF main int istat index 0 mta_item_list_t item_list 4 STRITEM MTA SUBJECT send input c STRITEM MTA TO root ITEM MTA MSG PROC msg proc ITEM MTA END LIST 0 exit mtaSend item list Messaging Server 6 2005Q1 MTA Developer s Reference 248 Chapter 8 mtaSend Routine Specification This chapter contains the functional specification of the mtaSend routine It includes the following sections e mtaSend Syntax
123. ception consider a call to mtaLog as being identical to calling the C run time library routine printf The call arguments for the two routines are identical including the formatting argument fmt The single exception is that unlike printf a call to mtaLog always produces a single line of output to the channel s log file Consequently do not attempt to write either partial or multiple lines with a single call to mtaLog Do not include a terminating line feed or other record terminator in the output That is do not put a n at the end of the formatting string A time stamp with a resolution of hundredths of a second prefaces each line of diagnostic output generated with mtaLog The time stamp uses the system clock and is reported in the local time zone Return Values None Example char buf 64 mtaLog Version d d d mtaVersionMajor mtaVersionMinor mtaVersionRevision mtaLog Date time 55 mtaDateTime buf NULL sizeof buf 0 mtaLog Postmaster address s mtaPostmasterAddress NULL NULL The following output is generated by the preceding code example 12 43 24 62 Version 6 0 0 12 43 24 62 Date time Thu 01 May 2003 12 43 24 0700 12 43 24 63 Postmaster address postman mailhub siroe com mtaLog 216 Messaging Server 6 2005Q1 MTA Developer s Reference mtaLogv mtaLogv Write diagnostic output to the channel s log file Syntax void mtaLogv co
124. char UniqueName char buf size t maxbuf const char suffix strcpy buf tmp mtaUniqueString buf 5 NULL maxbuf 5 strcat buf suffix return buf Explanatory Text for Numbered Comments The numbered list that follows has explanatory text that corresponds to the numbered comments in Code Example 4 2 on page 63 1 The global context data structure for this example This is passed to mtaDequeueStart as the ctx1 call argument 2 Per thread data structure used by dequeue threads While mt aDequeueStart creates each dequeue thread it is up to the process message routine to actually create any per thread context it might need 3 Initialize the global context before calling mt aDequeueStart 4 Initiate dequeue processing by calling ntabequeueStart The first call argument is a pointer to the global context Each time mtaDequeueStart calls process message it passes in the global context pointer as the second argument In this example mtaDequeueStart is not told to limit the number of dequeue threads it uses 5 If the call to mtaDequeueStart succeeds the program exits normally 6 Ifthe call to mtaDequeueStart fails then a diagnostic error message is displayed and the program exits with an error status 7 Each dequeue thread calls process done as it exits This program cleans up and destroys any per thread contexts created by the process message routine 8 The program gene
125. code argument passed to mtaDecodeMessage The list of item codes must be terminated with an item code with a value of 0 Additional Description Place an upper limit on the depth of nested MIME multiparts that will be parsed When this limit is reached no further parsing of deeper nested multiparts is performed and the parts handed over for inspection include as text content these deeper nested multiparts By default no limit is imposed When dealing with looping notification messages it is possible for the looping message to become deeply nested This item code must be followed by one additional call argument whose value is the integer valued upper limit to impose max levels Place an upper limit on the total number of message parts that will be parsed When this limit is reached no further parsing of parts is performed By default no limit is imposed This item code must be followed by one additional call argument whose value is the integer valued part limit to impose max parts When specified the MIME parser will first translate non MIME formatted data to MIME By default this translation is not performed Specify a pointer to an item list array The item list array must be terminated with a final array entry with an item code value of 0 For further information on item lists see Item Codes and Item Lists on page 28 Data supplied by the input routine pointed to by the input argument uses a single byte carr
126. comment 8 if gctx amp amp gctx debug mtaLog Dequeue thread done id d context p messages d tctx id tctx tctx count Now clean up and destroy the context if tctx gt fp fprintf tctx gt fp QUIT n fclose tctx gt fp free tctx process message Called by mtaDequeueStart to process a single message See explanatory comment 9 static int process 0855806 void my ctx 2 void my ctx 1 mta dq t dg const char env from size t env from len my global context t gctx my thread context t tctx int ires ret type const char to env id line size t len char notify buf 100 This should never happen but just to be safe we check if my ctx 1 my ctx 2 return MTA_ABORT The pointer to our global context was passed as my ctx 1 See explanatory comment 10 gctx my global context t my ctx 1 In this example we just use the per thread context to 1 Track the output file for this dequeue thread across 0 repeated calls and 2 to count how many messages have been output by this dequeue thread Chapter 4 Dequeuing Messages 65 A Complex Dequeuing Example Code Example 4 2 A Complex Dequeue Example Continued See explanatory comment 11 Xy if my ctx 2 First call to process 0655806 by this dequeue thread Store a pointer to our context t
127. comments in Code Example 4 1 on page 56 1 Tostart the dequeue processing mtaDequeueStart is called and it calls process message which processes each queued message Since process message uses stdout for its output only one message can be processed at a time To effect that behavior mt aDequeueStart is called with the MTA THREAD MAX THREADS set to one 2 If the call to mtaDequeueStart succeeds the program exits normally 3 Ifthe call to mtaDequeueStart fails a diagnostic error message is displayed and the program exits with an error status 4 process message is called by mtaDequeueStart for each queued message 5 The private context in process message tracks whether or not this is the first time the routine has been called On the first call the memory pointed at by my ctx 2is guaranteed to be NULL 6 Theroutine obtains each envelope recipient address one at a time using calls to mtaDequeueRecipientNext 7 Each recipient is marked as delivered using mtaDequeueRecipientDispostion An actual channel program would typically not make this call until after processing the message further 8 lfprocess message returns without first dequeuing the message mtaDequeueStart defers the message for a later delivery attempt 9 Theroutine calls mtaDequeueLineNext to read the message header and body one line at a time When there are no more lines to read mtaDequeueLineNext returns a status of
128. ct is passed for use as an inspection routine 4 The input routine decode read This routine provides the message to be decoded 200 bytes at a time Note that providing only 200 bytes at a time is arbitrary the routine could if it chose provide the entire message or 2000 bytes at atime or arandom number of bytes on each call After the entire message has been supplied subsequent calls to decode read return the MTA EOF status 5 The inspection routine decode inspect For each atomic message part this routine is called repeatedly The repeated calls provide line by line the part s header and decoded content 6 Fora given message part the final call to decode inspect provides no part data This final call serves to give decode inspect a last chance to accept or discard the part when outputting the final form of the message via an optional output routine supplied to mtaDecodeMessage That optional routine is not used here Messaging Server 6 2005Q1 MTA Developer s Reference 92 The Output Destination 7 Thepart number for this message part is obtained with a call to mtaDecodeMessageInfoInt MIME Message Decoding Simple Example Output This example shows the output generated by the program in Code Example 5 1 on page 89 18 Content type text plain charset us ascii 1H Content disposition inline 1T This is a TIS test message 2H Content type application postscript 2H Content tran
129. ctx my thread context t calloc 1 sizeof my thread context t if tctx Insufficient virtual memory give up now return MTA_ABORT my_ctx_2 void tctx Debug output if gctx debug tctx id mtaDequeueThreadId dq mtaLog Dequeue thread starting 10 0 context p tctx id tctx This dequeue thread has already called process message previously El tctx my thread context t my ctx 2 Send a HELO or a RSET if 0 tctx count gctx max count char buf 1024 int fd Need to send a HELO Send a QUIT if we ve already sent a HELO previously if tctx count gt 0 amp amp tctx gt fp fprintf tctx gt fp QUIT n fclose tctx gt fp tctx gt fp NULL Now open a file fd open UniqueName buf sizeof buf bsmtp O_WRONLY O_CREAT O_EXCL 0770 if fd lt 0 tctx gt fp fdopen fd w return MTA_ABORT Now send the HELO fprintf tctx gt fp HELO s n mtaChannelToHost NULL NULL MTA_DQ CONTEXT dq 0 66 Messaging Server 6 2005Q1 MTA Developer s Reference A Complex Dequeuing Example Code Example 4 2 A Complex Dequeue Example Continued else We ve already sent a HELO Send a RSET to start a new message fprintf tctx gt fp RSET n tctx gt count Output the command MAIL FROM from adr RET return typ
130. d The buffer should have a length of at least BIGALFA_SIZE 1 bytes MTA STRTRUERR The supplied option name is too long Its length must not exceed ALFA SIZE bytes Example In the code example that follows the value of an option named mail urlis retrieved Before calling mtaOptionString a default value is set for the variable to receive the value of the option If the option was not specified then the variable will retain that default setting If the option was specified then the variable will assume the value set by that specification char url 1024 strcpy url mail to webmasterG8siroe com mtaOptionString opt mail url 0 url NULL sizeof url mtaPostmasterA ddress Obtain the MTA local postmaster address Chapter 6 MTA SDK Reference 7 mtaPostmasterAddress Syntax const char mtaPostmasterAddress const char address size t len int item code Arguments Arguments Description address Optional pointer to receive the memory address of the string buffer containing the MTA local postmaster address The string will be NULL terminated A value of NULL may be passed for this argument len Optional address of a size t to receive the length in bytes of the postmaster address A value of NULL may be passed for this argument item code Reserved for future use A value of zero 0 must be passed for this argument Description This routine returns a pointer to a NULL terminated strin
131. d by mtaDequeueStart env_to The recipient address to effect the setting for This must be the recipient s envelope To address as returned by mt aDequeueRecipientNext and not some transformation of that address If a value of zero is passed for the env_to_len argument then this string must be NULL terminated env_to_len The length in bytes of the recipient address env_to This length does not include any NULL terminator If a value of zero is passed for this argument then the recipient address string must be NULL terminated disposition The delivery status disposition to set for this recipient address See the description section that follows for further details item_code An optional list of item codes See the description section that follows for a list of item codes The list must be terminated with an integer argument with value 0 Description Before completing processing of a queued message the disposition of each envelope recipient must be set either by repeated calls to mtaDequeueRecipientDisposition or by means of the MTA_DISP item code for mtaDequeueMessageFinish For the former a call should be made for each envelope recipient address For the latter the disposition set with MTA_DISP applies to all envelope recipients overriding any previous settings made with mtaDequeueRecipientDisposition The delivery status dispositions and their descriptions are listed in the table that follows Pass one of these values for the di
132. d goes through see Debugging Programs and Logging Diagnostics on page 33 otring valued Call Arguments Strings passed as call arguments to the MTA SDK routines also have an associated length argument Use of the length argument is optional that is if you do not know the length or do not wish to supply it then supply a value of zero for the length argument However in that case the supplied string must be NULL terminated so that the SDK routine can determine the string s length When a non zero length is supplied then the string does not need to be NULL terminated Wherever possible the SDK routines return pointers to output strings rather than returning the strings themselves These pointers are always thread safe however when associated with an SDK context they often are only valid as long as the context itself is valid Such limits will be noted in the description of the individual routines in Chapter 4 Dequeuing Messages In some cases an output string buffer must be supplied as with the mtaDateTime and mtaUniqueString routines Itis worthwhile to note that internally the MTA has several basic string sizes Users of the SDK generally do not need to concern themselves with this fact However at times it may be helpful to be aware of them as they can provide an upper bound on the length of various strings you might encounter As shown in the following table for instance channel names will never be longer than CHANLENGTH
133. d ourLog our context t ctx const char fmt Chapter 6 MTA SDK Reference 7 mtaOptionFinish char new fmt 10240 va list ap Genrate a new formatting string that includes as a prefix the value of ctx id then followed by the contents of the supplied formatting string snprintf new fmt sizeof new fmt id d s ctx id fmt va_start ap fmt mtaLogv new_fmt ap va_end ap mtaOptionFinish Dispose of an option context Syntax void mtaOptionFinish mta opt t opt ctx Arguments Arguments Description opt ctx An option context created by mt aOptionStart Description Option contexts should be disposed of with a call to mtaOptionFinish The one exception to this rule are option contexts returned by mtaDecodeMessageInfoParams While those contexts may be passed to mta0ptionFinish they do not need to be because mt aDecodeMessage will automatically dispose of them Return Values None Example mtaOptionFinish opt 218 Messaging Server 6 2005Q1 MTA Developer s Reference mtaOptionFloat mtaOptionFloat Interpret and return an option s value as a floating point number Syntax int mtaOptionFloat mta opt t opt_ctx const char name size t len double val Arguments Arguments Description opt ctx An option context created by mtaOptionStart A NULL value is permitted for this argument When a NULL is passed then no op
134. d with any of the other MTA_ENC_ item codes The default encoding is ENC UNKNOWN The item address and item length fields are ignored for this item code MTA ENC HEXADECIMAL Encode data from all subsequent input sources using a hexadecimal encoding This setting may be changed with any of the other MTA ENC item codes The default encoding is MTA ENC UNKNOWN The item address and item length fields are ignored for this item code MTA ENC NONE Data from all subsequent input sources is left unencoded that is not encoded This setting may be changed with any of the other MTA_ENC_ item codes The default encoding is MTA ENC UNKNOWN The item address and item length fields are ignored for this item code MTA ENC PATHWORKS Encodes multipart and binary message contents using the OpenVMS Pathworks format This setting may be changed with any of the other MTA_ENC_ item codes The default encoding is MTA ENC UNKNOWN The item address and item length fields are ignored for this item code MTA ENC QUOTED PRINTABLE Encode data from all subsequent input sources using MIME s quoted printable encoding This setting may be changed with any of the other MTA_ENC_ item codes The default encoding is MTA UNKNOWN The item address and item length fields are ignored for this item code MTA ENC UNKNOWN Data from all subsequent input sources is left unencoded that is not encoded This setting may be changed with any of the oth
135. ddress The value of the delivery flags is a logical OR of the deliveryflags channel keyword values on each channel the message has been enqueued to as it flows through the MTA This item code must be followed by one additional call argument the address of a size t to receive the delivery flag setting Retrieve the destination domain name if any the Job Controller has associated with this dequeue thread When the channel is marked with the single sys channel keyword then the Job Controller tries to give each dequeue thread for that channel all messages destined for the same host as determined by the domain name in the recipient envelope addresses This item code must be followed by two additional call arguments 1 The address of a pointer to receive the address of the NULL terminated destination domain name 2 The address of a size t to receive the length of that domain name A NULL value may be passed for the domain len size t dflags const char domain 5126 t domain len MTA DELIVERY FLAGS MTA DOMAIN argument 157 Chapter 6 MTA SDK Reference Description Obtain the envelope ID associated with this message If the message was submitted to the MTA using the SMTP NOTARY extension RFC 1891 then this will be the value of the ENVID parameter supplied with the SMTP MAIL FROM command In all other cases it will be an envelope ID assigned by the MTA This item code must be followed by two addit
136. ddress type MTA FOPEN Unable to initialize the MTA SDK can t read one or more configuration files Issue the following command for further information imsimta test rewrite Chapter 6 MTASDK Reference 5 mtaBlockSize Error Status Codes Continued Description MTA NO There are two reasons to get this return value 1 Unable to rewrite the supplied address Either the address is syntactically invalid or it does not match any channel 2 Unable to initialize the MTA SDK Issue the following command for further information imsimta test rewrite MTA NOSUCHITEM An invalid item code was specified MTA STRTRUERR There are two reasons to get this return value 1 Supplied address string is too long length can not exceed ALFA_SIZE bytes 2 The supplied buffer to receive the channel name is too small Example None mtaBlockSize Obtain the size in bytes of an MTA block size unit Syntax size t mtaBlockSize void Arguments None Description The MTA measures message sizes in units of blocks Units of blocks are used for instance when logging message sizes and for the MTA FRAGMENT BLOCKS item code in the mtaEnqueueStart routine By default a block is 1024 bytes However sites can change this setting with the BLOCK SIZE option in the option dat file Programs using the SDK can translate units of bytes to blocks by dividing the number of bytes by the value returned by mtaBlockSize
137. de An optional list of item codes See the description section that follows for a list of item codes The list must be terminated with an integer argument with value 0 Description Call the mtaInit routine to initialize the MTA SDK As part of the initialization process the SDK will load the MTA configuration This loading process will be the typical cause of initialization failures either there s an error in a configuration file a missing but required configuration file or a configuration file can t be accessed for reading To prevent that last error case ensure that your programs run under a UID that has read access to the MTA configuration files especially the compiled configuration file produced by the imsimta cnbuild utility While there is no benefit to doing so it is safe to call mtaInit multiple times either before or after calling ntaDone To de initialize the SDK use mtaDone mtalnit mtalnit 212 Messaging Server 6 2005Q1 MTA Developer s Reference mtalnit Although the MTA SDK is self initializing the initialization must occur while the process is single threaded As such multi threaded programs must call mtaInit and must do so while still single threaded When the SDK is initialized the SDK can be told using an item code whether or not the calling program will be functioning as an interactive utility or not When being used by an interactive utility such as a management utility or a user ag
138. dentifier specifying which value to return See the description that follows for the list of permitted values for this argument Description This routine is used to obtain integer valued information about the current message part When mtabecodeMessage calls either a user supplied inspection or output routine it provides a decode context describing the current message part being processed The following table lists the values for the item argument and gives a description of each Values Description MTA DECODE DTYPE Data type associated with this part The returned values will be MTA DATA NONE MTA DATA HEADER MTA DATA TEXT Or MTA DATA BINARY MTA DECODE PART NUMBER Sequential part number for the current part The first message part is part 0 the second part is 1 the third part is 2 and so on Return Values Upon normal successful completion the value of the requested item is returned In the event of an error a value of 1 is returned and mta errno is set to indicate the error status code The following table lists the error status codes for this routine and gives an example of each Error Status Codes Description MTA BADARGS A NULL value was supplied for the dct x call argument MTA NOSUCHITEM An invalid value was supplied for the item call argument 146 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDecodeMessagelnfoParams Example part number mtaDecodeMessageInfoIn
139. des Both of those examples represent intermediate processing channels that handle previously constructed messages As such they do not need to alter the existing message header and they preserve any MTA envelope fields Messaging Server 6 2005Q1 MTA Developer s Reference 46 Delivery Processing Options Envelope fields Delivery Processing Options Envelope fields A variety of delivery processing options may be set through the MTA SDK These options are then stored in the message s envelope and are generically referred to as envelope fields Options which pertain to the message as a whole are set with mtaEnqueueStart Options which pertain to a specific recipient of the message are set with mtaEnqueueTo These options per message and per recipient include the following These flags are used to communicate information between channels For instance a scanning channel might set the flag to indicate suspected spam content A delivery channel could then see that the flag is set and at delivery time add a header line indicating potential spam content These flags may also be set using the deliveryflags channel keyword These flags influence whether delivery or non delivery notification messages are generated They can be set on a per recipient basis Typically they are used to request a delivery receipt Another common usage is for bulk mail to request no notifications neither delivery nor non delivery Delivery flags No
140. e ENVID id env id NULL See explanatory comment 12 ret type MTA NOTIFY DEFAULT mtaDequeueInfo dq MTA ENV ID amp env id NULL MTA NOTIFY FLAGS amp ret type 0 fprintf tctx gt fp MAIL FROM lt s gt RET s s s n env from NotifyToStr ret type NULL env id ENVID env id env id Output the command RCPT TO lt to adr gt NOTIFY notify type for each recipient address See explanatory comment 13 Bl while ires mtaDequeueRecipientNext dg amp to amp len MTA NOTIFY FLAGS amp ret type 0 fprintf tctx gt fp RCPT TO s NOTIFY s n to NotifyToStr ret type notify buf Indicate that delivery to this recipient succeeded See explanatory comment 14 mtaDequeueRecipientDisposition dq to len MTA DISP DELIVERED 0 If ires MTA_EOF then we exited the loop normally otherwise there s been an error of some sort See explanatory comment 15 if ires MTA EOF return ires ox ox o gt Now output the message itself fprintf tctx gt fp DATA n See explanatory comment 16 while ires mtaDequeueLineNext dg amp line amp len Check to see if we need to dot stuff the link if len 1 amp amp line 0 Chapter 4 Dequeuing Messages 7 A Complex Dequeuing Example Code Example 4 2 A Complex Dequeue Example Continued fprintf tctx gt fp Now ou
141. e Item Codes MTA ADR NOSTATUS on page 253 MTA ADR STATUS on page 253 MTA BCC on page 253 MTA BLANK on page 253 MTA CC on page 254 MTA CHANNEL on page 254 MTA CFILENAME on page 254 MTA CFILENAME NONE on page 254 MTA CTYPE on page 254 MTA ENC BASE64 on page 255 MTA ENC BASE85 on page 255 MTA ENC BINHEX on page 255 MTA ENC BTOA on page 255 MTA ENC COMPRESSED BASE64 on page 255 MTA ENC COMPRESSED BINARY on page 255 MTA ENC COMPRESSED UUENCODE on page 256 MTA ENC HEXADECIMAL on page 256 249 MTA E ONE on page 256 PATHWORKS on page 256 MTA E UNKNOWN on page 256 6 C MTA ENC QUOTED PRINTABLE on page 256 6 C MTA E UUENCODE on page 257 MTA END LIST on page 257 MTA ENV FROM on page 257 MTA FRAGMENT BLOCKS on page 257 MTA FRAGMENT LINES on page 258 MTA ENV TO on page 257 MTA FROM on page 258 MTA HDR ADRS on page 258 MTA HDR BCC on page 259 MTA HDR CC on page 259 MTA HDR FILE on page 259 MTA HDR LINE on page 259 MTA HDR NOADRS on page 259 MTA HDR NORESENT on page 260 MTA HDR PROC on page 260 MTA HDR RESENT on page 260 MTA HDR TO on page 260 MTA HDRMSG FILE on page 260 MTA HDRMSG PROC on page 261 MTA IGNORE ERRORS on page 261 MTA INTERACTIVE on page 261 MTA ITEM LIST on page 261 MTA MAX TO on page 261 MTA MODE B
142. e added to both the envelope recipient list as well as the message s header For further information about Bcc see the note on page 202 None The address is an active transport address that should also appear in a Cc header line As such the address will be added to both the envelope recipient list as well as the message s header MTA BCC MTA CC 202 Messaging Server 6 2005Q1 MTA Developer s Reference mtaEnqueueTo Description Specify additional envelope delivery flags to set for this recipient The logical OR of any existing setting for the recipient and the value here supplied will be used for the recipient s delivery flag setting The existing setting for the recipient will be either the message s setting which was set with mtaEnqueueStart or any setting copied over from the dequeue context for this recipient with the DQ CONTEXT item code This item code should be followed by one additional call argument the value to combine with any existing setting Ignore any previous envelope delivery flag setting for the recipient and replace the setting with the value specified with this item code This item code should be followed by one additional call argument the delivery flag setting to effect When a dequeue context is supplied using this item code the specified envelope recipient address is compared to the envelope recipient list for the queued message represented by the dequeue cont
143. e additional required arguments and gives a description of each Description Use the MTA DISP item code to set the disposition for all recipients of the message This disposition will override any prior disposition settings This item code must be followed by one additional call argument the disposition value to set See the description of mtaDequeueRecipientDisposition fora discussion of the disposition settings Specify a pointer to an item list array The item list array must be terminated with a final array entry with an item code value of zero For further information on item list usage see Item Codes and Item Lists on page 28 The reason for ascribing the disposition to this recipient address This reason might then appear in any delivery or non delivery status notification for that recipient This item code must be followed by two additional call arguments 1 the address of the string containing the reason text 2 The length in bytes of the reason text If a value of zero is passed for the length then the reason text must be NULL terminated mtaDequeueRecipientDisposition Additional Arguments size_t disposition mta_item_list_t item list const char reason size t reason len Item Codes MTA DISP MTA ITEM LIST MTA REASON 168 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDequeueRecipientNext Return Values Return Values Description 0 Normal successful completion
144. e address may not exceed ALFA SIZE bytes MTA HDR CC Specify a header only carbon copy Cc address that is an inactive recipient which should only appear in the message s header The item address and item length fields specify the address and length of a string containing a Cc address The length of the address may not exceed ALFA SIZE bytes MTA HDR FILE Specify the name of an input file containing message header lines The first input file may be a file containing a message header In this case it should be specified using this item code rather than MTA MSG FILE This will ensure that the input file receives the proper processing such as is not encoded accessed using text mode access The mtaSend routine uses the header lines from the input file to form an initial message header This initial header is then modified as necessary This functionality is useful when forwarding mail Note that any recipient addresses in the header file will be ignored unless MTA_HDR_ADRS is also specified The item address and item length fields specify the address and length of a text string containing the input file s name The length of the string may not exceed ALFA SIZE bytes MTA HDR LINE Specify an additional header line to include in the message header The item address and item length fields specify the address and length of the header line field name and body to place in the message header The length of the string may not exc
145. e copy or copies to the MTA channel queues Consequently errors returned by this routine are typically caused by either site imposed limits that is the message size exceeds a site configured limit or file system related problems for example the disk is full write errors to the disk When mtaEnqueueFinish returns an MTA NO error message there is often extended error information available This information may be retrieved with the MTA_REASON item code This extended error information takes the form of a text string suitable for writing as diagnostic output Before calling mtaEnqueueFinish to complete an enqueue operation be sure that the envelope recipient list has been specified with mtaEnqueueTo and any header lines and content have been written with mtaEnqueueWrite or mtaEnqueueWriteLine Chapter 6 MTA SDK Reference 7 mtaEnqueueFinish When cancelling an enqueue operation no message is submitted to the MTA and any temporary files that may have been created are disposed of To cancel an enqueue operation specify the MTA ABORT item code The following table lists the item codes for this routine their additional arguments and gives a description of each Item Codes Additional Arguments Description MTA ABORT None Cancel the current enqueue operation The message represented by the enqueue context will not be enqueued to the MTA MTA ITEM LIST mta item list t Specify a pointer to an item list a
146. e loop occurs when mtaDequeueRecipientNext returns an MTA EOF status Any other status signifies an error ires MTA EOF MTA Developer s Reference A Simple Virus Scanner Example Code Example 5 2 int siz nq aif define if CHE whi 98 Messaging Server 6 2005Q1 A Simple Virus Scanner Example Code Example 5 2 Decoding MIME Messages Complex Example Continued error report options ires mtaDequeueRecipientNext goto done bad Begin the MIME decode of the message See explanatory comment 8 CHECK mtaDecodeMessage mtaDecodeMessage Private context is our options void options Input is the message being dequeued MTA DECODE DQ void dq Output is the message being enqueued MTA DECODE NQ void nq Inspection routine decode inspect Convert non MIME formats to MIME MTA DECODE THURMAN 0 Finish the enqueue NOTE IT S IMPORTANT TO DO THIS before DOING THE DEQUEUE YOU WILL LOSE MAIL IF YOU DO THE DEQUEUE FIRST and then THE ENQUEUE FAILS See explanatory text 9 x CHECK mtaEnqueueFinish mtaEnqueueFinish nq 0 nq Finish the dequeue CHECK mtaDequeueFinish mtaDequeueMessageFinish dq 0 All done with this message wp return MTA OK done bad Abort any ongoing enqueue or dequeue if nq mtaEnqueueFinish ng MTA ABORT 0 if dq
147. e routines are designed such that if the requested option does not exist then no value is returned This allows code to assign to a variable an option s default value then attempt to retrieve an explicitly set value from the option file During the retrieval the address of the variable can be passed If the option is specified in Chapter6 MTA SDK Reference 223 the option file then the value of the variable will be replaced with the value from the option file If the option is not specified then the default value stored in the variable is left unchanged Code examples of such usage are provided in the individual routine descriptions Once finished obtaining the values of any options unload the options from memory and dispose of the option context with mtaOptionFinish When the underlying option file does not exist mtaoptionsStart still returns a success status code However a NULL value is returned for the pointer to the option context The other option routines accept a NULL value for an option context pointer and will behave as though the requested option is not specified in the option file This behavior reflects the fact that MTA option files are considered optional If a channel s option file does not exist then the channel is supposed to use its default settings for its options This also simplifies coding allowing programs not to have to worry about whether or not the option file exists and whether or
148. eMessageFinish dq MTA ABORT 0 if nq mtaEnqueueFinish nq MTA ABORT 0 return MTA NO 20613 an implmentation of the rotate by 13 translation See explanatory comment 16 static char rotl3 char c if A lt c amp amp c lt Z return c A 13 26 A else if a lt c amp amp c lt z return c a 13 26 a else return c rotl3str Perform a 20813 translation on a string of text See explanatory comment 17 static const char rotl3str rotl13 buf t dst const char src size t srclen size_t i char ptr 0 13 2 buf t rbuf dst First call If so then allocate a 20 13 buf t structure x if rbuf rbuf calloc 1 sizeof rot13 buf t if rbuf return NULL dst rbuf Need a larger buffer If so then increase the length of rbuf gt buf d if rbuf maxlen gt srclen rbuf gt buf Chapter 4 Dequeuing Messages 7 Intermediate Channel Example Code Example 4 3 Intermediate Channel Example Continued size t 1 char tmp Round size up to the nearest 2k 1 2048 int srclen 2047 2048 tmp char malloc 1 if tmp return NULL if rbuf gt buf free rbuf buf rbuf gt buf tmp rbuf gt maxlen 1 A Now rot13 our input ptr rbuf gt buf for i 0 i gt srclen i ptr rot13 src All done x r
149. eMessagelnfoString The following table lists the values for the iten call argument and gives a description of each Values Description TA DECODE CCHARSET The character set specified with the CHARSET parameter of the part s Content type header line If the part lacks a CHARSET Specification then the value us ascii will be returned TA DECODE CDISP Value of the Content disposition header line less any optional parameters If the part lacks a Content disposition header line the returned value will be a zero length string TA DECODE CSUBTYPE The content subtype specified with the part s Content type header line for example plain for text plain gif for image gif Defaults to plain when the part lacks a Content type header line MTA DECODE CTYPE The major content type specified with the part s Content type header line for example text for text plain image for image gif Defaults to text when the part lacks a Content type header line Return Values mtaDecodeMessageInfoString always returns a value for the CHARSET parameter of the Content type header line When the Content type header line is not present it returns the MIME default value us ascii Upon normal successful completion a pointer to the requested string is returned In addition if pointers were provided in the str and len call arguments the address of the string and its length are returned In the event of an error a NULL val
150. ed calls to mtaDequeueRecipientNext the read point into the underlying message file is positioned at the start of the actual message Specifically at the start of the message s outermost header Calling mt aDequeueLineNext advances this read point with each call moving it towards the end of the message To reposition the read point back to the start of the message that is to the start of the message s outermost header call ntabequeueRewind Use this call if a program needs to make a second pass through a message For example a program might scan a message s content before actually processing it Return Values Return Values Description 0 Normal successful completion MTA BADARGS A NULL value was supplied for the dg ctx call argument or an invalid dequeue context was supplied for dq_ctx MTA ORDER Call made out of sequence The call was made either before the recipient list has been exhausted with mtaDequeueRecipientNext or after the message had been dequeued or deferred with mtaDequeueMessageFinish MTA THREAD The MTA SDK detected simultaneous use of the dequeue context by two different threads Example None mtaDequeueStart mtaDequeueStart Initiate message dequeue processing 172 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDequeueStart Syntax int mtaDequeueStart void etx mta_dq_process_message_t process_message mta_dq_process_done_t process_done int item_code
151. ed messages after first transforming their content with the 20613 transformation include lt stdio h gt include lt stdlib h gt include mtasdk h typedef struct size t maxlen char buf t xotl3 buf t static mta dq process done t process done static mta dq process message t process message static char rotl3 char c Chapter 4 Dequeuing Messages 3 Intermediate Channel Example Code Example 4 3 Intermediate Channel Example Continued static const char 0 138 2 20 13 2 buf t dst const char src size t srclen int main int ires Initialize the MTA SDK if ires mtalnit 0 mtaLog mtaInit returned d sWn ires mtaStrError ires 0 return 1 Start the dequeue loop See explanatory comment 1 yf ires mtaDequeueStart NULL process message process done 0 Check the return status See explanatory comment 2 if lires Success return 0 Produce an error message See explanatory comment 3 mtaLog mtaDequeueStart returned d s ires mtaStrError ires 0 And exit with an error return 1 process done Clean up the private context my ctx 2 used by e process message See explanatory comment 4 X static void process done void my ctx 2 void my ctx 1 0 13 2 buf t rbuf Messaging Server 6 2005Q1 MTA Developer s Reference 74
152. ed notification messages themselves must have an empty envelope From address Chapter6 MTA SDK Reference 163 mtaDequeueMessageFinish e Notifications must not be sent for messages with an empty envelope From address These two rules combine to prevent certain broad classes of message loops The MTA SDK strictly adheres to these Internet requirements Whenever a temporary processing error occurs and the channel can no longer process a queued message processing of the message should be deferred until a later time Processing for all recipients is deferred regardless of any prior disposition settings Temporary processing errors include such errors as insufficient virtual memory network problems disk errors and other unexpected processing errors The following table lists the item codes for this routine the additional arguments they take and gives a description of each one Item Codes Additional Arguments Description MTA ABORT None When this item code is specified processing of the message is deferred for all recipients of the message The message is left in the channel s queue and a later processing attempt is scheduled MTA DISP size t disposition Use the MTA DISP item code to set the disposition for all recipients of the message This disposition will override any prior disposition settings This item code must be followed by one additional call argument the disposition value to set See the description of mtaDequeueReci
153. edly called by mt aDequeueStart until there are no more queued messages in need of processing One call is made per message to be processed Unless otherwise instructed mtaDequeueStart will use multiple threads of execution to process queued messages Each thread of execution will repeatedly invoke the caller supplied routine once for each message to be processed Thus by default the caller supplied routine is expected to be thread safe That is it is expected to support being called simultaneously by more than one thread of execution If the caller supplied routine is not thread safe then mt aDequeueStart can be instructed to use a single thread of execution as illustrated in A Complex Dequeuing Example on page 63 Basic Dequeuing Steps The following basic steps are necessary to dequeue messages 1 Initialize SDK resources and data structures with mtaInit 2 Call mtaDequeueStart passing it the address of the caller supplied routine that is to be used to process each message When mt aDequeueStart is called it does not return until all queued messages requiring processing have been processed thus blocking the thread calling it until it is finished 50 Messaging Server 6 2005Q1 MTA Developer s Reference Caller Supplied Processing Routine 3 Foreach queued message requiring processing an execution thread created by mtaDequeueStart calls the routine whose address was provided in Step 2 Thread
154. eed ALFA SIZE bytes Any number of header lines may be added Use one item list entry per header line MTA NOADRS Recipient addresses must be explicitly specified and any addresses in an input header file will be ignored but will still appear in the message header The item address and item length fields are ignored for this item code Chapter8 mtaSend Routine Specification 259 This is the default action for recipient addresses found in input header files MTA HDR NORESENT Specify MTA HDR NORESENT to cause additional addresses to be added to existing header lines rather than through the introduction of Resent header lines The item address and item length fields are ignored for this item code MTA HDR PROC Specify the address of a procedure that will return one line at a time header lines for the message header The item address field specifies the address of the procedure to invoke The item length field is ignored The calling format that must be used by the procedure is given in Message Headers and Content on page 240 in this manual MTA HDR RESENT The MTA HDR RESENT action selects the default behavior whereby Resent header lines are added as necessary to the message header when the associated header line appears in any input header files For instance a Resent to header line will be added if a To header line already appears The item address and item length fields are ignored for this item code MT
155. egated Administrator Guide e Sun Java System Communications Services Enterprise Deployment Planning Guide Sun Java System Communications Services Schema Migration Guide e Sun Java System Communications Services Schema Reference e Sun Java System Communications Services Event Notification Service Guide e Sun Java System Communications Express Administration Guide Preface 5 Accessing Sun Resources Online e Sun Java System Communications Express Customization Guide Accessing Sun Resources Online For product downloads professional services patches and support and additional developer information go to the following e Download Center http wws sun com software download e Professional Services http www sun com service sunps sunone index html e Sun Enterprise Services Solaris Patches and Support http sunsolve sun com e Developer Information http developers sun com prodtech index html Contacting Sun Technical Support If you have technical questions about this product that are not answered in the product documentation go to http www sun com service contacting Related Third Party Web Site References Sun is not responsible for the availability of third party web sites mentioned in this document Sun does not endorse and is not responsible or liable for any content advertising products or other materials that are available on or through such sites or resources Sun will not
156. ell are not displayed in the examples Depending on which operating system you are using you will see a variety of different command line prompts However you should enter the command as it appears in the document unless specifically noted otherwise 14 Messaging Server 6 2005Q1 MTA Developer s Reference Related Documentation Helated Documentation The http docs sun con M web site enables you to access Sun technical documentation online You can browse the archive or search for a specific book title or subject Messaging Server Documents Use the following URL to see all the Messaging Server documentation http docs sun com coll MessagingServer 05q1 The Messaging Server product suite contains other products such as Sun Java System Console Directory Server and Administration Server Documentation for these and other products can be found at the following URL http docs sun com db prod sunone In addition to the software documentation see the Messaging Server Software Forum for technical help on specific Messaging Server product questions The forum can be found at the following URL http swforum sun com jive forum jsp forum 15 Communications Services Documents Use either one of the following URLs to see the documentation that applies to all Communications Services products http docs sun com coll MessagingServer 05q1 The following documents are available Sun Java System Communications Services Del
157. en the channel name specified with the PMDF CHANNEL environment variable is not defined in the MTA configuration file This error may also be returned when the Job Controller s configuration file lacks a CHANNEL section matching the specified channel An invalid item code was specified Return Values MTA NETWORK MTA NO MTA NOMEM MTA NOSUCHCHAN MTA NOSUCHITEM Example For an example of mtaDequeueStart see Decoding MIME Messages Complex Example on page 96 Other Considerations for mtaDequeueStart This section contains supplementary information concerning mt aDequeueStart It covers the following topics Multiple Calls to mtaDequeueStart on page 177 e Message Processing page 177 e Message Processing Procedure on page 177 5 5 pag e process_message Routine on page 178 e process_done Routine on page 0 e Thread Creation Loop on page 181 mtaDequeueStart 176 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDequeueStart Multiple Calls to mtaDequeueStart A channel program can call mtaDequeueStart multiple times either sequentially or in parallel In the latter case the program would need to create threads so as to effect multiple simultaneous calls to mtaDequeueStart However just because this can be done does not mean that it is appropriate to do so In the former case of multiple sequential calls there s no need to be making r
158. ent 2 An invalid dequeue context was supplied for dq ctx 3 A required argument to an item code was NULL MTA_NO An attempt was made to retrieve recipient information before calling mtaDequeueRecipientNext MTA NOSUCHITEM An invalid item code was specified MTA THREAD The MTA SDK detected simultaneous use of the dequeue context by two different threads Example The following code fragment illustrates how this routine is used to retrieve the delivery flags and intermediate recipient address for each recipient address int dflags istat const char to ito while istat mtaDequeueRecipientNext dq amp to NULL 0 mtaDequeueInfo dq MTA DELIVERY FLAGS amp dflags MTA IRCPT TO amp ito NULL 0 printf Delivery flags d n Intermediate recipient address s n dflags ito if istat MTA_EOF printf An error occured s n mtaStrError istat mtaDequeueLineNext mtaDequeueLineNext Read the next line of the message from the queued message file 160 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDequeueLineNext Syntax int mtaDequeueLineNext mta dq t dq ctx const char line size t len Arguments Arguments Description dq ctx A dequeue context created by mtaDequeueStart line Optional address of a pointer to receive the address of the next line of the message The line will not be NULL terminated A value of NULL may be passed for this argument
159. ent the SDK ensures that accounting files are closed after every operation that records accounting information This prevents the accounting file from being left open by a single process for long periods of time To specify that the SDK will be used by an interactive utility specify the INTERACTIVE item code By default the SDK assumes that it will be run by a channel program or other program that wishes to achieve maximum performance while using the SDK This corresponds to the CHANNEL item code Also when the SDK self initializes itself it assumes MTA_CHANNEL and not MTA_INTERACTIVE As part of initializing the SDK a number of diagnostic facilities can be enabled These are enabled using the MTA DEBUG item codes described in the following table These diagnostic facilities may also be enabled at any time using the mtaDebug routine Additional Arguments Description F None Indicate that the SDK is being used by a channel program or other non interactive program By default this is the assumed usage Interactive programs should use the MTA_INTERACTIVE item code MTA DEBUG DECODE None Enable diagnostic output from the low level MIME decoding routines used by the MTA SDK This diagnostic output may prove helpful when attempting to understand any MIME conversions that occur either when enqueuing messages to the MTA and the destination channel is configured to invoke MIME conversions for example mar
160. ent address It could be syntactically invalid refused by a mapping table such as SEND ACCESS Consider using the MTA REASON item code MTA NOSUCHITEM An invalid item code was specified MTA ORDER The call was made out of order the message s envelope recipient list has already been terminated by a call to mtaEnqueueWrite or mtaEnqueueWriteLine MTA STRTRUERR The supplied envelope To address or original envelope To address is too long Neither may exceed a length of ALFA SIZE bytes Example This routine is used in Decoding MIME Messages Complex Example on page 96 mtaEnqueueWrite Write message data to the message being submitted Syntax int mtaEnqueueWrite mta nq t nq ctx const char strl size t 161 const char str2 Zero or more string pointer length pairs can be supplied to this routine The list of pairs must be terminated by a NULL call argument 206 Messaging Server 6 2005Q1 MTA Developer s Reference mtaEnqueueWrite Arguments Arguments Description nq ctx Pointer to an enqueue context created with mt aEnqueueStart strl Pointer to a string of text to write to the message The string must be NULL terminated if a value of zero is passed for 1 leni The length in bytes not including any NULL terminator of the string str1 If a value of zero is passed for this argument then the string 5521 must be NULL terminated Str2 Pointer to a second string of text to write to the mess
161. ent disposition header line if any The parsed list is returned as a pointer to an option context For further information see mtaDecodeMessageInfoParams The content subtype specified with the part s Content type header line for example plain for text plain gif for image gif Defaults to plain when the part lacks a Content type header line Obtain with mt aDecodeMessageInfoString The major content type specified with the part s Content type header line for example text for text plain image for image gif Defaults to text when the part lacks a Content type header line Obtain with mt aDecodeMessageInfoString Parameter list to the Content type header line if any The parsed list is returned as a pointer to an option context For further information see mtaDecodeMessageInfoParams Data type associated with this part Obtain with mtaDecodeMessageInfoInt Message Code MTA DECODE CCHARSET MTA DECODE CDISP MTA DECODE CDISP PARAMS MTA DECODE CSUBTYPE MTA DECODE CTYPE MTA DECODE CTYPE PARAMS MTA DECODE DTYPE 142 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDecodeMessage Message Code Continued Description Sequential part number for the current part The first message part is part 0 the second part is 1 the third part is 2 and so on Obtain with mtaDecodeMessageInfoInt MTA DECODE PART NUMBER Item Codes The table that follows lists the item codes for the item
162. envelope information to be automatically copied from the message being dequeued to the new message being enqueued When used with the latter it causes per recipient information to be automatically copied Note that channel programs should not attempt to explicitly copy envelope information other than the envelope From and envelope recipient addresses The MTA DQ CONTEXT item code should always be used to implicitly perform the copy The reason for this is straightforward if a program attempts to do the copy explicitly by querying the fields one by one from the message being dequeued and then setting them one by one in the message being enqueued then any new envelope fields introduced in later versions of Messaging Server will be lost unless the program is updated to explicitly know about those new fields too Use MTA ENV TO Intermediate processing channels should use the MTA ENV TO item code with mtaEnqueueTo rather than the MTA TO CC and MTA_BCC item codes This tells the MTA that the recipient address being specified should be added to only the message s envelope and not also to a Resent To Resent Cc Or Resent Bcc header line Code Example 4 3 on page 73 and Code Example 5 2 on page 96 illustrate the use of the MTA ENV TO item code Both of those examples represent intermediate processing channels which are handling a previously constructed message As such they do not need to alter the existing message header Messa
163. epeated calls When mt aDequeueStart returns the channel no longer needs immediate processing and has been in that state for MTA_JBC_ATTEMPTS_MAX MTA_JBC_RETRY_INTERVAL seconds Instead the channel program should exit thereby freeing up system resources The Job Controller will start a new channel program running when there are more messages to process In the latter case of multiple parallel calls there is again no need to do so If there is an advantage to running more threads than a single call generates then the channel s threaddepth channel keyword setting should be increased so that a single call does generate more threads The only exception to either of these cases might be if the multiple calls are each for a different channel Even then however the advantage of so doing is dubious as the same effect can be achieved through the use of multiple processes one for each channel Message Processing When mtaDequeueStart is called a communication path with the MTA Job Controller is established The Job Controller is then asked if there are messages to be processed for the channel Typically there will be messages to process since it is the Job Controller that normally starts channel programs and it does so when there are queued messages in need of processing Based upon information obtained from the Job Controller mt aDequeueStart will then begin to create non joinable processing threads Each processing thread immediatel
164. equeued from the MTA is represented within the SDK by an opaque dequeue context of type mta dq t Each dequeue context is created by mtaDequeueStart and passed to a caller supplied processing procedure Each dequeue context is then destroyed when mtaDequeueMessageFinish is called Throughout the dequeue process the message being dequeued is referenced through its dequeue context Under typical usage a program will have multiple threads operating each simultaneously dequeuing a message However it is not permitted for two threads to simultaneously use the same dequeue context in calls to the SDK In the event the SDK detects simultaneous usages it returns the MTA THREAD error Message Processing Threads When mtaDequeueStart is called a communication path with the MTA Job Controller is established The Job Controller is then asked if there are messages to be processed for the channel Typically there will be messages to process since the Job Controller normally only starts channel programs when there are queued Dequeuing Messages 26 Messaging Server 6 2005Q1 MTA Developer s Reference String valued Call Arguments messages in need of processing Based upon information obtained from the Job Controller mtaDequeueStart will then begin to create non joinable processing threads Each processing thread immediately begins processing the queued messages For further information about the exact steps a message processing threa
165. er 6 2005Q1 MTA Developer s Reference mtaEnqueueStart Description Explicitly specify the name of the channel under which to enqueue this message That is explicitly specify the name of the source channel to use for this message submission The name specified will override any name implicitly specified with the MTA DO CONTEXT item code This item code must be followed by two additional call arguments 1 The address of the string containing the channel name 2 The length in bytes of that channel name If a value of zero is specified for the length then the channel name string must be NULL terminated Specify additional envelope delivery flags to set for this message The logical OR of any existing setting and the value here supplied will be used for the message s delivery flag setting In general the delivery flag setting associated with a message will be the logical OR of the values set by each channel a message has travelled through Note that channels also can set this value with the deliveryflags channel keyword When this item code is not used the delivery flags inherited from a supplied dequeue context will be used If no dequeue context is supplied then the value of the delivery flags will be set to zero This item code should be followed by an additional call argument the value to combine with any existing setting Ignore any previous envelope delivery flag setting for the message and replace the setting with
166. er MTA ENC item codes The default encoding is MTA ENC UNKNOWN The item address and item length fields are ignored for this item code Item Codes 256 Messaging Server 6 2005Q1 MTA Developer s Reference Item Codes MTA ENC UUENCODE Encode data from all subsequent input sources using UUENCODE This setting may be changed with any of the other MTA_ENC_ item codes The default encoding is MTA ENC UNKNOWN The item address and item length fields are ignored for this item code MTA END LIST Terminate an item list This item code when encountered signals the end of the item list The item address and item length fields are ignored for this item code MTA ENV FROM Specify the envelope From address to associate with a message The item address and item length fields specify the address and length of a text string containing the envelope From address to use for the message submission The length of the string may not exceed ALFA SIZE bytes Only one envelope From address may be specified The MTA ENV FROM action should be used when the envelope From address is not a local address When the address is a local address then only the user name should be specified using the MTA USER action If this action and the MTA USER actions are not specified then the user name associated with the current process will be used Do not use this item code in conjunction with the MTA USER or MTA SUB USER item codes MTA ENV TO Specify
167. erate a non delivery notification if required Recipient address forwarded to another address or sent into a non RFC 1891 NOTARY mail system The message s NOTARY information was however preserved There is no need to generate a relayed notification message Recipient address forwarded to another address or gatewayed to a non RFC 1891 NOTARY mail system the messages NOTARY information was not preserved generate a relayed notification message if required For this recipient return the message as undeliverable Generate a non delivery notification if required This disposition is intended for use by queue management utilities It is not intended for channel programs Unable to process this recipient address Processing failed due to timing out This disposition is intended for use by the MTA Return Job Channel programs should not use this disposition Symbolic Name Continued MTA DISP FAILED MTA DISP RELAYED MTA DISP RELAYED FOREIGN MTA DISP RETURN MTA DISP TIMEDOUT 5 Dequeue the message with mtaDequeueMessageFinish The message is not actually removed from the channel queue until this final step This helps ensure that mail is not lost should the channel program fail unexpectedly or some other unexpected disaster occurs When this routine is called the resulting processing depends on the disposition of the envelope recipient addresses reported with mtaDequeueRecipientDisposition see Step 4 in this tas
168. erence mtaDequeueRewind Return Values Return Values Description 0 Normal successful completion MTA BADARGS This value was returned for one of the following reasons 1 A NULL value was supplied for the dg ctx call argument 2 An invalid dequeue context was supplied for dq ct x 3 ANULL value was supplied for a required item code argument MTA NOMEM Insufficient virtual memory MTA EOF The recipient list has been completely read there are no further recipient addresses to return MTA THREAD Concurrent use of the dequeue context by two different threads has been detected Example This code fragment illustrates an intermediate processing channel using this routine to fetch recipient addresses int dflags istat const char to itos while istat mtaDequeueRecipientNext dq amp to NULL MTA DELIVERY FLAGS amp dflags MTA IRCPT TO amp ito NULL 0 printf Delivery flags d n Intermediate recipient address s n dflags ito if istat MTA EOF printf An error occured s n mtaStrError istat mtaDequeueRewind Reset the read point to the start of the message Syntax int mtaDequeueLineNext mta dq t dq ctx Chapter 6 MTA SDK Reference 1 Arguments Arguments Description dq ctx A dequeue context created by mtaDequeueStart Description Repositions the read point back to the start of the message After obtaining a message s recipient list by repeat
169. erface JavaMail JavaHelp J2SE iPlanet the Duke logo the Java Coffee Cup logo the Solaris logo the SunTone Certified logo and the Sun ONE logo are trademarks or registered trademarks of Sun Microsystems Inc in the U S and other countries All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International Inc in the U S and other countries Products bearing SPARC trademarks are based upon architecture developed by Sun Microsystems Inc Legato and the Legato logo are registered trademarks and Legato NetWorker are trademarks or registered trademarks of Legato Systems Inc The Netscape Communications Corp logo is a trademark or registered trademark of Netscape Communications Corporation The OPEN LOOK and Sun TM Graphical User Interface was developed by Sun Microsystems Inc for its users and licensees Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry Sun holds a non exclusive license from Xerox to the Xerox Graphical User Interface which license also covers Sun s licensees who implement OPEN LOOK GUIs and otherwise comply with Sun s written license agreements This product includes software developed by Computing Services at Carnegie Mellon University http www cmu edu computing Products covered by and information contained in this service manual are controlled by U S Export Control law
170. ess and item length fields are ignored for this item code MTA ENC BINHEX Encode data from all subsequent input sources using the BINHEX encoding This setting may be changed with any of the other MTA_ENC_ item codes The default encoding is MTA ENC UNKNOWN The item address and item length fields are ignored for this item code MTA ENC BTOA Encode data from all subsequent input sources using the UNIX binary to ASCII BTOA encoding This setting may be changed with any of the other MTA ENC item codes The default encoding is MTA ENC UNKNOWN The item address and item length fields are ignored for this item code MTA ENC COMPRESSED BASE64 Encodes data from all subsequent input sources using MIME s BASE64 encoding after first compressing it using Gnu zip This setting may be changed with any of the other MTA_ENC_ item codes The default encoding is ENC UNKNOWN The item address and item length fields are ignored for this item code MTA ENC COMPRESSED BINARY Compress the data with Gnu zip No other encoding of the data will be done This setting may be changed with any of the other MTA_ENC_ item codes The default encoding is MTA ENC UNKNOWN The item address and item length fields are ignored for this item code Chapter8 mtaSend Routine Specification 255 MTA ENC COMPRESSED UUENCODE Encode data from all subsequent input sources using UUENCODE after first compressing the data with Gnu zip This setting may be change
171. essage body lines are written with the routines mtaEnqueueWrite and mtaEnqueueWriteLine Example Enqueued messages may be seen in the MTA queue directories and are merely ASCII text files In the following sample message lines 1 and 2 are the message envelope the next four lines are the header and the rest of the lines are the body jdoe8siroe com msmith siroe com Date Tues 1 Apr 2003 15 01 PST From John Doe To Mike Smith Subject Lunch today Mike Just confirming our lunch appointment today 1 11 meet you at the restaurant at noon John NOTE As stated earlier do not directly read from or write messages to the MTA message queues Always use the SDK routines or Callable Send The file structure of messages in the MTA queues are subject to change In addition site specific constraints may be placed on things such as encodings and character set usage The SDK routines automatically handle these and other issues Threads and Enqueue Contexts Each individual message being enqueued to the MTA is represented within the SDK by an opaque enqueue context of type mta_ng_t This enqueue context is created by mtaEnqueueStart and destroyed by mtaEnqueueFinish Throughout the enqueue process the message being enqueued is referenced through its Enqueuing Messages 24 Messaging Server 6 2005Q1 MTA Developer s Reference Dequeuing Messages enqueue context A program using the SDK may simultaneous
172. essages Complex Example Output on page 108 Chapter 5 Decoding Messages 95 A Simple Virus Scanner Example After the Messaging Server product is installed these programs can be found in the following location msg server base examples mtasdk Some lines of code are immediately preceded by a comment of the format See explanatory comment N where N is a number The numbers are links to some corresponding explanatory text in the section that follows this code see Explanatory Text for Numbered Decoding MIME Messages Complex Example Remove potentially harmful content from queued messages Comments on page 107 virus scanner simple c x ox HF H include lt stdio h gt include lt stdlib h gt include lt string h gt include lt ctype h gt include mtasdk h A structure to store our channel options xf typedef struct Produce debug output int debug Unwanted MIME content types char bad_mime_types BIGALFA_SIZE 3 Length of bmt string size t bmt len Unwanted file types char bad file types BIGALFA _SIZE 3 f char msg options int ires const ct ct dctx char buf size t maxbuflen static int is bad file type our options t options mta opt t params const char param name char buf size t maxbuflen static int load options our options t options cons static void error report our options char fun
173. essful completion MTA BADARGS This value is returned for one of the following reasons 1 A NULL value was supplied for the ng ctx call argument 2 An invalid context was passed for nq ctx MTA THREAD Simultaneous use of the enqueue context by two different threads was detected Example None 186 Messaging Server 6 2005Q1 MTA Developer s Reference mtaEnqueueFinish mtaEnqueueFinish Complete or cancel a message enqueue operation Syntax int mtaEnqueueFinish mta nq t nq ctx int item code Arguments Arguments Description nq ctx An enqueue context created by mtaEnqueueStart item code An optional list of item codes See the description section that follows for a list of item codes The list must be terminated with an integer argument with value 0 Description Call ntaEnqueueFinish to complete an enqueue operation submitting a new message to the MTA for transport and delivery Alternatively call mtaEnqueueFinish with the MTA ABORT item code to cancel an enqueue operation without submitting a new message In either case when mtaEnqueueFinish is called the enqueue context passed to it nq ctx is disposed of and may no longer be used regardless of whether a success or error status code is returned When completing an enqueue operation the MTA does much of the actual enqueue work such as performing any configured header rewriting content transformation and actually writing the messag
174. eturn rbuf buf Explanatory Text for Numbered Comments 1 The dequeue processing is initiated by calling mtaDequeueStart In this example no global context is used hence the first call argument to mtaDequeueStart is NULL 2 If the call to mtaDequeueStart succeeds then the program exits normally 3 Ifthe call to mtaDequeueStart fails a diagnostic error message is displayed and the program exits with an error status 4 Each dequeue thread calls process done as it exits The intent is to allow the program to clean up and destroy any per thread contexts created by the process message routine In this case the buffer used by 20613562 is deallocated 5 The mtaDequeueStart routine calls process message once for each queued message to be processed On the first call by a dequeue thread the memory pointed at by my ctx 2 is NULL 78 Messaging Server 6 2005Q1 MTA Developer s Reference Intermediate Channel Example 6 A message enqueue starts The dequeue context da is provided so that per message envelope fields can be carried over to the new message from the message being dequeued 7 Eachenvelope recipient address is obtained one at a time with mtaDequeueRecipientNext When there are no more recipient addresses to obtain mtaDequeueRecipientNext returns the status MTA EOF 8 Each envelope recipient address is added to the recipient list for the new message being enqueued The MTA ENV T
175. ewind dq ctx while mtaDequeueLineNext dq ctx amp line amp len mtaEnqueueWriteLine nq ctx line len NULL mtaEnqueueError Retrieve an extended error message Chapter 6 MTA SDK Reference 185 mtaEnqueueError Syntax const char mtaEnqueueError mta nq t nq ctx const char message size t message len int item code Arguments Arguments Description nq ctx An enqueue context created by mtaEnqueueStart message Optional address of a pointer to receive the address of the NULL terminated error message text A NULL value may be supplied for this argument message_len Optional address of a size_t to receive the length in bytes of the error message text A NULL value may be supplied for this argument item_code Reserved for future use A value of zero must be supplied for this call argument Description When mtaEnqueueTo returns an MTA_NO error message there is often extended error information available which takes the form of a text string suitable for writing as diagnostic output To retrieve this information issue mt aEnqueueError immediately after receiving an MTA_NO error return from mt aEnqueueTo Return Values In the event of an error from mtaEnqueueError a NULL value will be returned and mta_errno is set to indicate the error status code The following table lists the error status codes and gives a description of them Error Status Codes Description 0 Normal succ
176. ext If a match is found envelope fields for the recipient are copied from the queued message to the new message being enqueued If no match is found an MTA NO error status is returned This item code must be followed by one additional argument the pointer to the dequeue context to use The address is an active transport address add it to the envelope recipient list Do not add it to any header lines This designation is often used by intermediate processing channels The address is not an active transport address do not add it to the envelope recipient list The address should however be added to a Bcc header line Note that since a Bcc header line is usually only placed in the message copy destined to the Bcc recipient use of this item code only arises when the Bcc recipient s header address differs from their transport address and consequently the two need to be added with separate calls to mtaEnqueueTo Chapter 6 MTA SDK Reference 203 Additional Arguments size t dflags size t dflags mta dq t dq ctx None None Continued ERY FLAGS ERY FLAGS ABS Item Codes MTA DELIVI MTA DELIVI MTA DO CONTEXT MTA ENV TO MTA HDR BCC mtaEnqueueTo Item Codes Continued Additional Arguments Description MTA HDR CC None The address is not an active transport address do not add it to the envelope recipient list The address should however be added to a Cc header line MT
177. ext was supplied for dct x 2 Arequired argument to an item code was NULL MTA NO Returned for one of two reasons 1 Invalid call Either no output routine is being used or the call was made from the output routine itself 2 Output errors encountered while attempting to write the output MTA NOSUCHITEM An invalid item code was specified Example The following code fragment shows how the routine is used to discard the message part mtaDecodeMessagePartDelete dctx 0 The following code fragment shows how to replace the message part with a text warning mtaDecodeMessagePartDelete dctx MTA REASON Warning virus infected message part was discarded 0 MTA DECODE CLANG en 2 MTA DECODE CCHARSET us ascii 8 0 The following code fragment shows the output generated by the preceding code example Content type text plain charset us ascii Content language en Warning virus infected message part was discarded See also Decoding MIME Messages Complex Example on page 96 Chapter 6 MTA SDK Reference 155 mtaDequeuelnfo mtaDequeuelnfo Obtain information associated with an ongoing message dequeue Syntax int mtaDequeueInfo mta dq t dq ctx int item code Arguments Arguments Description dq ctx A dequeue context created by mtaDequeueStart item code An optional list of item codes See the description section that follows for a list of item codes The list
178. ext with mt aDecodeMessage no further calls to mtaDequeueRecipientNext can be made e Calls to mtaDequeueLineNext can only be performed after a call to mtaDequeueRewind Caller Supplied Input Routine When using a caller supplied input routine to supply the message to be decoded specify MTA DECODE PROC for the input type argument and pass the address of the input routine as the input argument Chapter 6 MTA SDK Reference 139 The following code fragment shows the syntax of a caller supplied input routine int input routine void UGEX const char line size t line len The following table lists the arguments for a caller supplied input routine and gives a description of each Arguments Description ctx The caller supplied private context line A pointer to the start of the next line or section of data to return The line or data does not need to be NULL terminated line len The length in bytes of the line or block of data being returned A zero length signifies zero bytes of data That is a zero length does not cause mtaMessageDecode to automatically determine the length by searching for a NULL terminator On each successful call the input routine should return a status code of 0 MTA OK When there is no more message data to provide then the input routine should return MTA EOF The call that returns the last byte of data should return 0 itis the subsequent call that must return MTA_EOF In the eve
179. f program is a server that listens continually for incoming mail connections enqueuing received messages Site specific configuration information is loaded at initialization In the case of these long running programs the information can become stale due to changes to configuration information such as rewrite rules or channel definitions Subsequent calls to mtaInit do not accomplish this task A program must exit and restart in order to ensure that all configuration information is reloaded Keeping the Log File Available For Update A program that enqueues and dequeues messages may open the MTA log file mail log current For persistent programs care should be taken that this log file is not left open during periods of inactivity Otherwise activities that require exclusive access to this file will be blocked Before going idle persistent programs should call mt aAccount ingLogClose The log file will automatically reopened when needed NOTE The MTA log file mail 1og current is not the log written to by mtaLog Chapter 2 MTA SDK Programming Considerations 9 Miscellaneous Programming Considerations 40 Messaging Server 6 200501 MTA Developer s Reference Chapter 3 Enqueuing Messages The MTA SDK provides routines with which to construct a mail message and then submit the message to the MTA The MTA then effects delivery of the message to its recipients The act of submitting a message to the MTA for delivery is refer
180. for a list of item codes The list must be terminated with an integer argument with value 0 Description The first step in processing a queued message is to retrieve its list of envelope recipient addresses This is done by repeatedly calling mt aDequeueRecipientNext until a status code of MTA EOF is returned Note that each call that returns a recipient address will return a status code of 0 MTA Ok The final call which returns MTA_EOF will not return a recipient address The processing of the list of envelope recipient addresses will in general be unique to each channel Intermediate processing channels should simply re enqueue a new message and copy the envelope recipient list verbatim over to the new message being enqueued being sure to specify the MTA ENV TO and MTA DQ CONTEXT item codes to mtaEnqueueTo The envelope recipient list must be read in its entirety before attempting to read the message itself with mtaDequeueLineNext Failure to do so will result in an MTA ORDER error being returned by mtaDequeueLineNext This routine accepts the same item codes as mtaDequeueInfo The code fragments are equivalent also compare the examples Consequently the mt aDequeueInfo routine might appear superfluous However it also serves as a means of obtaining in a single non repeated call information about the overall message itself such as the message s envelope ID 170 Messaging Server 6 2005Q1 MTA Developer s Ref
181. for the ng ctx call argument 2 An invalid enqueue context was supplied for ng ctx or a required argument to an item code was NULL MTA_FCREATE Unable to create a disk file MTA_FIO Error writing to a disk MTA_ORDER Call made out of order No envelope recipient addresses have been supplied MTA_THREAD Simultaneous use of the enqueue context by two different threads was detected Example The code fragment that follows shows two ways to produce the same results They both write two header lines to the message mtaEnqueueWrite ng From sue siroe com n 0 NULL mtaEnqueueWrite ng Subject test n 0 NULL mtaEnqueueWrite ng From sue siroe com nSubject test n 0 NULL The following code fragment shows the two header lines output by each code fragment in the preceding code example From sue siroe com Subject test This code fragment demonstrates how to terminate the message header by writing a blank line mtaEnqueueWrite ng in 0 NULL mtaEnqueueWrite 208 Messaging Server 6 2005Q1 MTA Developer s Reference mtaEnqueueWriteLine The following code fragment shows a single call to mt aEnqueueWrite that writes out an entire header including the terminating blank line mtaEnqueueWrite nq Date today nFrom sue siroe com n To bob siroe com nSubject test n n 0 NULL The following code example shows an alternate way of writing the routine call but
182. g enqueued To start at the beginning of the queued message that is to start at the beginning of its outermost header specify a value of 1 for the rewind call argument So doing is equivalent to first calling mtaDequeueRewind before mtaEnqueueCopyMessage 184 Messaging Server 6 2005001 MTA Developer s Reference mtaEnqueueError Return Values Return Values Description 0 Normal successful completion BADARGS This value is returned for one of the following reasons 1 A NULL value was supplied for either the nq ctx or dq ctx call arguments 2 Invalid contexts were passed for either or both of those call arguments MTA FCREATE Unable to create a temporary file to hold data for the new message being enqueued MTA FIO An I O error occurred while attempting to write data to a message file ORDER Call made out of order Either no recipients have yet been specified for the new message with mt aEnqueueTo or the recipient list of the queued message has not been completely read with mtaDequeueRecipientNext MTA THREAD Simultaneous use of either the enqueue or dequeue context by two different threads was detected Example The following code fragment specifies starting at the beginning of the queued message by using the rewind call argument mtaEnqueueMessageCopy nq ctx dq ctx 1 The code fragment that follows illustrates a second less efficient way of copying the message mtaDequeueR
183. g Messages Chapter 4 Dequeuing Messages Chapter 5 Decoding Messages Chapter 6 MTA SDK Reference Chapter 7 Using Callable Send mtaSend Chapter 8 mtaSend Routine Specification Appendix A Error Status Codes Summary 12 Messaging Server 6 2005Q1 MTA Developer s Reference Conventions Used in This Book Conventions Used in This Book The tables in this section describe the conventions used in this book Examples Edit your 1ogin file Use 1s ato list all files 9 You have mail su Password The file is located in the msg sor base bin directory Read Chapter 6 in the User s Guide These are called class options Do not save the file Typographic Conventions The following table describes the typographic changes used in this book Typographic Conventions Meaning Any text that appears on the computer screen or text that you should type Can be API and language elements HTML tags web site URLs command names file names directory path names onscreen computer output sample code Text that you should type when it appears within a code example or other onscreen computer output A placeholder in a command or path name that you should replace with a real name or value for example a variable Also can be a book title new term or word to be emphasized Table 2 Typeface AaBbCc123 Monospace AaBbCc123 Monospace bold AaBbCc123 Italic
184. g a channel that deletes all queued messages after first counting the number of lines in each message for accounting purposes More typical of such a channel would be to supply NULL for the 1ine argument but pass a non zero address for the 1en argument That would then allow the channel to count up the number of bytes in the deleted message Chapter 6 MTA SDK Reference 1 mtaDequeueMessageFinish Return Values Return Values Description 0 Normal successful completion MTA_BADARGS A NULL value was supplied for the dg 66 call argument or an invalid dequeue context was supplied for dq_ctx MTA EOF Message file has been completely read no further lines to return Example int istat const char line size t len while istat mtaDequeueLineNext dq ctx amp line amp len printf s n len line if istat MTA EOF printf An error occured s n mtaStrError istat mtaDequeueMessageFinish Complete a message dequeue or defer a message for later processing Syntax int mtaDequeueMessageFinish mta dq t dq ctx int item code Arguments Arguments Description dq ctx A dequeue context created by mtaDequeueStart item code An optional list of item codes See the description section the follows for a list of item codes The list must be terminated with an integer argument with value 0 Description Before completing processing of a queued message the disposition of each envel
185. g containing the MTA local postmaster address This address is suitable for instance for inclusion in the From header line of notification messages as shown in the code example for this routine Itis usually not a good idea for programs to send mail to the postmaster s address In many situations sending mail to the postmaster when failures occur can lead to mail loops if the mail sent to the postmaster itself fails and generates a message to the postmaster which then fails and generates yet another message to the postmaster and so on On a successful completion the address of the string buffer containing the postmaster s address is returned using the address call argument That same address is also returned as the return status Return Values In the event of an error a value of NULL is returned as the status and mta errnois set with a status code indicating the underlying error Error Status Codes Description MTA FOPEN Unable to initialize the MTA SDK Unable to read one or more configuration files For further information issue the following command imsimta test rewrite Messaging Server 6 2005Q1 MTA Developer s Reference 228 mtaStackSize Error Status Codes Description MTA NO Unable to initialize the MTA SDK For further information issue the following command imsimta test rewrite Example The following example shows how to use this routine to include the postmaster address in the From header
186. g whether the line comes from a header text part or binary part See explanatory comment 5 static int decode inspect void ctx mta decode t dctx int data type const char data size t data len static const char types H T B See explanatory comment 6 if data type DATA NONE return MTA OK Chapter 5 Decoding Messages 1 A Simple Decoding Example Code Example 5 1 Decoding MIME Messages Continued See explanatory comment 7 printf d s sWn mtaDecodeMessageInfoInt dctx MTA DECODE PART NUMBER types data type data len data return MTA OK Explanatory Text for Numbered Comments The following numbered explanatory text corresponds to the numbered comments in Code Example 5 1 on page 89 1 The MIME message to be decoded It is a multipart message with two parts The first part contains text the second part a PostScript attachment 2 The private context to be passed to mtaDecodeMessage and in turn passed by it to the supplied input routine decode read The input routine uses this context to track how many bytes of the input message it has supplied to mtaDecodeMessage 3 The call to mtaDecodeMessage An input routine decode read is supplied to provide the message to be decoded Since the message source has each record terminated by line feeds the MTA TERM LF option is also specified The routine decode inspe
187. ging Server 6 2005Q1 MTA Developer s Reference 72 Intermediate Channel Example Use Rewrite Rules to Prevent Message Loops Finally intermediate processing channels often require special rewrite rules in order to prevent message loops Specifically loops in which mail re enqueued by the intermediate processing channel is queued back to the intermediate processing channel See Preventing Mail Loops when Re enqueuing Mail on page 37 for further information on this topic Intermediate Channel Example The sample program in this section in Code Example 4 3 converts the body of each queued message and then re enqueues the converted messages back to the MTA The conversion process involves applying the rot 13 encoding used by some news readers to encode potentially offensive message content To configure the MTA to run this channel see Running Your Enqueue and Dequeue Programs on page 31 Also refer to Preventing Mail Loops when Re enqueuing Mail on page 37 which discusses configuring special rewrite rules for programs re enqueuing dequeued email Some lines of code in this example are immediately preceded by a comment of the format See explanatory comment N where N is a number The numbers are links to some corresponding explanatory text found in Explanatory Text for Numbered Comments on page 78 Code Example 4 3 Intermediate Channel Example intermediate channel c A channel program that re enqueues queu
188. going message enqueue operation may be obtained with mt aEnqueueInfo The information to obtain is specified through the use of item codes Arguments to the item codes provide memory addresses through which to return the requested data String pointers returned by mtaEnqueueInfo are only valid during the life of the enqueue context Once the enqueue has been completed the associated pointers are no longer valid The following table lists the item codes for this routine their additional arguments and gives a description of each Item Codes Additional Arguments Description MTA_ALIAS EXPAND size t value Return the setting of the alias expansion flag Normally this flag has a nonzero value that indicates that alias expansion should be done for all envelope recipient addresses When the flag has a value of zero alias expansion will not be performed The value of the flag is set with the mtaEnqueueStart routine This item code must be followed by one additional argument the address of size t to store the setting s value in 190 Messaging Server 6 2005Q1 MTA Developer s Reference mtaEnqueuelnfo Item Codes Continued Additional Arguments Description MTA ADR SORT size t value Obtain the setting of the address sorting flag Normally this flag has a non zero value that indicates that the list of envelope recipients written to each message copy in the MTA channel queues are to be sorted in ascending orde
189. h no more than the specified number of lines The individual fragments are MIME compliant messages that use MIME s message partial content type MIME compliant mailers or user agents that receive the fragments may automatically re assemble the fragmented message MTA channels must be marked with the defragment keyword in order for automatic message re assembly to occur The item length field specifies the maximum number of message lines per message or message fragment By default no limit is imposed MTA FROM Specify the address to use in the message header s From header line The item address and item length fields specify the address and length of a text string containing the From address The length of the string may not exceed ALFA SIZE bytes Only one From address may be specified If this action is not used then the From header line will be derived from the envelope From address MTA HDR ADRS Specify MTA HDR ADRS to request that the message also be sent to recipient addresses found in any input header files The item address and item length fields are ignored for this item code Item Codes 258 Messaging Server 6 2005Q1 MTA Developer s Reference Item Codes MTA HDR BCC Specify a header only Bcc address that is an inactive recipient which should only appear in the message s header The item address and item length fields specify the address and length of a string containing a Bcc address The length of th
190. h the subtype and charset information and placed in a Content type header line The item code must be followed by two additional call arguments 1 The language string 2 The length in bytes of that string If a value of zero is passed for the length then the string must be NULL terminated Specify a pointer to an item list array The item list array must be terminated with a final array entry with an item code value of 0 For further information on item lists see Item Codes and Item Lists on page 28 Specifies the content and length of caller supplied text or data used to replace the deleted message part The item code must be followed by two additional call arguments 1 The language string 2 The length in bytes of that string If a value of zero is passed for the length then the string must be NULL terminated Additional Arguments const char subtype size t subtype len const char type size_t type len mta item list t item list const char text size t text len mtaDecodeMessagePartDelete Continued E CSUBTYPE E CTYPE Item Codes MTA DECODI MTA DECODI MTA ITEM LIST MTA REASON 154 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDecodeMessagePartDelete Return Values Return Values Description 0 Normal successful completion MTA BADARGS Returned for one of two reasons 1 A NULL value was supplied for the dctx call argument an invalid decode cont
191. hat channel name If a value of 0 is passed for the length the channel name must be NULL terminated Use the channel associated with the specified dequeue context This item code must be followed by one additional call argument a pointer to a dequeue context generated by mtaDequeueStart Specify a pointer to an item list array that is terminated with a final array entry that has an item code value of 0 For further information on item lists see Item Codes and Item Lists on page 28 Item Codes Additional Arguments MTA CHANNEL const char channel size t channel len MTA DQ CONTEXT mta dq t dq ctx MTA ITEM LIST mta item list t item list When none of the above item codes are specified the channel name is taken from the runtime environment using PMDF CHANNEL environment variable On successful completion the host name is stored in the buffer pointed at by the host argument and the value of the host argument is returned Return Values In the event of an error mtaChannelToHost will return NULL but will set lists the error status codes for this routine mta errno The following table Error Status Codes Description MTA BADARGS A NULL value was supplied for either of these two argument 1 The host argument in the routine call ment to an item code 2 An argu MTA FOPEN Unable to initialize the MTA SDK Unable to read one or more configuration files Issue the following command for fu
192. he MTA SDK if ires mtaInit 0 56 Messaging Server 6 2005Q1 MTA Developer s Reference A Simple Dequeue Example Code Example 4 1 A Simple Dequeue Example Continued y 77 mtaLog mtaInit returned d s n ires mtaStrError ires 0 return 1 Start the dequeue loop Since this example uses stdout for output we indicate that we only support a single thread MTA THREAD MAX THREADS 1 XJ See explanatory comment 1 ires mtaDequeueStart NULL process_message NULL MTA THREAD MAX THREADS 1 0 Check the return status kf See explanatory comment 2 if lires Success return 0 Print an error message to stderr See explanatory comment 3 mtalog mtaDequeueStart returned d s n ires ires mtaStrError ires 0 And exit with an error return 1 See explanatory comment 4 static int process message void my ctx 2 void my ctx 1 mta dq t dg const char env from Size t env from len int ires const char to line size t len See explanatory comment 5 if my ctx 2 1 my ctx 2 void 1 printf HELO n else printf RSET n Chapter 4 Dequeuing Messages 57 A Simple Dequeue Example Code Example 4 1 A Simple Dequeue Example Continued Output the command MAIL FROM lt from adr gt printf MAIL FROM lt s gt n env from
193. he debug log file mtaLogv Write to the debug log file MIME Parsing and Decoding These routines are used to parse and decode a MIME formatted message Routine Name Description mtaDecodeMessage Decode a MIME formatted message can also convert non MIME formats to MIME mtaDecodeMessagePart Copy Copy a message part mtaDecodeMessagePartDelete Delete a message part mtaDecodeMessageInfoInt Obtain the value of an integer valued parameter taDecodeMessageInfoString Obtain the value of a string valued parameter El mtaDecodeMessageInfoParams Obtain the Content type or Content disposition parameter list Miscellaneous These routines are used for miscellaneous tasks Routine Name Description mtaAccountingLogClose Close the MTA accounting log file 0 mtaAddressToChannel Determine which channel an address rewrites to mtaBlockSize Obtain the value of the MTA BLOCK_SIZE option 114 Messaging Server 6 2005001 MTA Developer s Reference Summary of SDK Routines Description Obtain the channel name for the running program Determine the host name associated with a channel Generate a date time string for use in an RFC 822 Date header line Obtain the postmaster s address Obtain the minimum thread stack size needed for arbitrary SDK operations Generate a unique string Obtain the major version number of the MTA SDK Obtain the minor version number of the MTA SDK Obtain the revision num
194. he first usage mode while Decoding MIME Messages Complex Example on page 96 illustrates the second Inspection Routine Key to either usage mode for mt aDecodeMessage is the inspection routine pointed to with the inspect argument The mtaDecodeMessage routine presents each atomic message part to the inspection routine one line at a time The presentation begins with the part s header lines Once all of the header lines have been presented the lines of content are presented next The following points should also be noted Message parts need not have any content A common example is a single part message with no content for which the sender used the Subject header line to express their message e Inthe case of a non multipart message the message has a single part The header for this sole part is the header for the message itself As noted previously there may or may not be any content to this single part e Inthe case of a multipart message individual parts need not have a part header In such cases MIME defaults apply and imply that the content is text plain using the US ASCII character set e Regardless of the value of the Content transfer encoding header line the content presented will no longer be encoded Inthe case of a multipart message the outermost header is not presented However it may be inspected by means of an output routine For a discussion of the output routine see Output Routine that follows The
195. he option file If it is important to know whether or not the option was specified then use mtaOptionString to test to see if the option was specified as shown in the code example Chapter 6 MTA SDK Reference 221 Return Values Return Values Description 0 Normal successful completion MTA STRTRUERR The supplied option name is too long Its length must not exceed ALFA SIZE bytes Example In the following code example the value of an option named max blocks is retrieved Before calling mtaOptionInt a default value is set for the variable to receive the value of the option If the option was not specified in the option file then the variable will retain that default setting If the option was specified then the variable will assume the value set in the file blocks 1024 mtaOptionInt opt max blocks 0 amp blocks The following code example illustrates how upon return from mta0ptionString the code determines that the option was specified by whether or not the value of the buflen variable has changed char buf 1 size_t buflen buflen Oxffffffff mtaOptionString opt max blocks 0 buf amp buflen sizeof buf blocks specified buflen Oxffffffff 1 0 mtaOptionStart mtaOptionStart Open parse and load into memory an MTA option file 222 Messaging Server 6 2005Q1 MTA Developer s Reference mtaOptionStart Syntax int mtaOptionStart
196. he user name Use this item code when the envelope From address is a local address If the envelope From address is not a local address then the ENV FROM action should be used If this action and the MTA ENV FROM actions are not specified then the user name associated with the current process will be used On UNIX the process must have the same real UID as the root or mta account If the process lacks sufficient privileges the MTA ACCESS error will be returned Do not use this item code in conjunction with the MTA ENV FROM item code Item Codes 264 Messaging Server 6 2005Q1 MTA Developer s Reference Appendix A Error Status Codes Summary This appendix describes the error status codes returned by the MTA SDK and mtaSend The table that follows lists the error status codes with a generic interpretation of each For usage specific interpretations refer to the specific MTA SDK routine descriptions in Chapter 6 and the mtaSend item code descriptions in Chapter 8 Numeric Value Description 0 Normal successful completion 1 This error typically indicates that a site supplied access mapping table has refused an envelope recipient address with a permanent error These access mapping tables include SEND ACCESS ORIG SEND ACCESS MAIL ACCESS and ORIG MAIL ACCESS This error may also result when a mailing list has access controls which do not allow the attempted message submission to the list 2 A
197. iage return terminator to terminate each line of message data This option is ignored when input type has the value Item Codes Arguments MTA DECODE LEVELS MAX max levels MTA DECODE PARTS MAX max parts MTA DECODE THRURMAN None mta item list t item list MTA ITEM LIST MTA TERM CR None MTA DECODE DQ Chapter 6 MTA SDK Reference 143 Description Data supplied by the input routine pointed to by the input argument uses a two byte carriage return line feed terminator to terminate each line of message data This option is ignored when input type has the value MTA DECODE DQ Data supplied by the input routine pointed to by the input argument uses a single byte line feed terminator to terminate each line of message data This option is ignored when input type has the value MTA DECODE DQ Data supplied by the input routine pointed to by the input argument uses a two byte line feed carriage return terminator to terminate each line of message data This option is ignored when input type has the value MTA DECODE DQ Data supplied by the input routine pointed to by the input argument uses no line terminators Each call to the input routine returns a single complete line of message data This option is ignored when input type has the value MTA DECODE DQ Additional Arguments None None None None mtaDecodeMessage Item Codes Continued MTA TERM CRLF MTA TERM LF
198. idual parameters can be queried using mtaOptionString mtaOptionInt and mta0ptionFloat Program code need not worry about whether the underlying header line exists in the parts header If it does not then calls to obtain individual parameter values will succeed but return no value NOTE If the Content type header line is not present mtaOptionString returns an empty string This is in contrast to what happens when mtaDecodeMessageInfoString is used It always returns a value for the CHARSET parameter of the Content type header line If the Content type header line is not present it returns the MIME default value us ascii It is important to note that the option contexts returned by this routine are only valid during the lifetime of the associated decode context They are not valid after inspection or output of a new message part begins nor are they valid after mtaDecodeMessage returns Return Values Upon normal successful completion a pointer to an option context is returned In the event of an error a NULL value is returned and mta errnois set to indicate the error status code The following table lists the error status codes and gives a description of each Error Status Codes Description MTA BADARGS A NULL value was supplied for the dctx call argument or an invalid decode context was supplied for dct x MTA NOSUCHITEM An invalid value was supplied for the item call argument Messaging Server 6 2005Q1 MTA
199. ies ces recepere e reb Rea Chapter 4 Dequeuing Messages How Dequeuing Works 52 coi Basie Dequetinp Steps cunas ro i ren E ens Caller Supplied Processing Routine The process message Routine sees Messaging Server 6 2005Q1 MTA Developer s Reference A Simple Example ciuda cesa 56 Explanatory Text for Numbered Comments 2 59 Output from the Simple Dequeue Example celere o devas 60 Processing the Message Queue 402 020 des de e bn eb D dace ee EXE DE Res 60 The process done ROWING Rer IE IY E Hp e Ya o pODis O9 EP 62 A Complex Dequeuing Example comi be be eeRREMERUDER I Bre eae a 63 Explanatory Text for Numbered Comments cetera n et merit be ERR 69 Output from the Complex Dequeue Example 1 22 m nis ee n ERR ER RES 71 Intermediate processing channels vet iik qu oa eR Tew IE ERIS 71 Preserve Envelope Information 2 72 Use MTA ENV IQ icczesc e cg a p ERES eed Od 72 Use Rewrite Rules to Prevent Message Loops 2 0 73 Intermediate Channel Example siio ia dr ERR area din ped E ER E 73 Explanatory Text for Numbered Comments 78 Sample Input Message for the Intermediate Channel Example sseesss 80 Output from the Intermediate Channel Example esee een 80 Thread Creation Loop n mtaDequeueStatt comio le eek rer ees enis Pl RR Ride eu 80 Multiple Calls tomtaDequeueStart ccr cack cede ss eee wee ae ERR LESE E ES EA End 82
200. ime for which to generate the string representation To use the current local time pass a value of zero for this argument Description This routine generates an RFC 2822 compliant date and time string suitable for use in an RFC 822 Date header line To generate a date and time string for a specific time supply the time as the time argument Otherwise supply a value of 0 for the time argument and a date and time string will be generated for the current local time On successful completion the date and time string is stored in the buffer pointed at by the date argument and the value of the date argument is returned Return Values In the event of an error mtaDateTime will return NULL It will set the error status code in mta errno Error Status Codes Description MTA BADARGS A value of NULL was supplied for the date argument MTA STRTRU The date buffer is too small the returned value has been truncated to fit mtaDateTime 132 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDebug Example char buf 80 1 printf The current date and time is s n mtaDateTime buf NULL sizeof buf time t 0 mtaDebug Enable generation of MTA SDK diagnostic output Syntax int mtaDebug int item code Arguments Arguments Description item code An optional list of item codes The list must be terminated with an integer argument with value 0 Description Many of the low level MT
201. imultaneous calls to mtaDequeueStart However just because this can be done does not mean that it is appropriate to do so In the former case of multiple sequential calls there is no need to be making repeated calls When mtaDequeueStart returns the channel no longer needs immediate processing and has been in that state for the number of seconds represented by the following formula JBC ATTEMPTS MAX MTA JBC RETRY INTERVAL Instead the channel program should exit thereby freeing up system resources The Job Controller will start a new channel program running when there are more messages to process In the latter case of multiple parallel calls there is again no need to do so If there is an advantage to running more threads than a single call generates then the channel s threaddepth channel keyword setting should be increased so that a single call does generate more threads The only exception to either of these cases might be if the multiple calls are each for a different channel Even then however the advantage of so doing is dubious as the same effect can be achieved through the use of multiple processes one for each channel Calling Order Dependencies When you are constructing programs there is a calling order for the MTA SDK routines that must be observed some routines must be called before others Messaging Server 6 2005Q1 MTA Developer s Reference 82 Calling Order Dependencies Figure 4 1 vis
202. ing Programs Compiling and Linking Programs This section contains information useful for compiling and linking your C programs Compiling To declare the SDK routines data structures constant and error codes C programs should use the msg server base include mtasdk h header file Linking Instructions for Solaris The linking instructions that follow are for the Solaris platform The table that follows shows the link command used to link a C program to the SDK SERVER ROOT2msg svr base cc O program program c ISSERVER ROOT include L SERVER ROOT lib ove oe lmtasdk In the example msg server base is the directory path to the top level messaging Server directory and program is the name of your program If running the program in a standalone mode that is not under the Job Controller then the CONFIGROOT INSTANCEDIR IMTA TAILOR and the LD LIBRARY PATH environment variables must be defined See the imsimta shell script used to launch MTA programs and utilities for details Running Your Test Programs This section describes the tasks that are typically required for running your test programs that enqueue or dequeue messages The tasks are divided into two groups those used to run your test programs in a fully functional messaging environment and those needed if you want to run them manually Running in a Messaging Environment on page 35 5 ging pag e Manually Running Your Test Programs
203. ing Server 6 2005001 MTA Developer s Reference pem e hehe aie tow beats a NEU S 258 FRAGMENT LINES nod NN e M r 258 MTA HDR ADRS uoret e does debe cies a ETC E 258 MTA HADR BECC nai SA Ee danda Ra a 7 209 MTA HDR 66 Rex ere e y E TE EDI uae T Pre RW PIPqed e 259 cd t RE ae 259 MTA MTA HDR LINE IRR tae dena 7 259 MDA ADR NOXDRS eco bac ad eae eter Sa ee LEE e A Erie s ep dae 259 MTA HDR NORESENT 2 262 440 0080 eR peg e P REG pg 4a esha PETI DS E 260 MEA FIDIS PROC ate atra dada nas e REM 260 MTA HDR RESENT ci a wae 260 Sita 200 0 A 06 MITA EIDIS TO ci MTA HDRMSG BILE ouvir roiie tt adk aE S ROTERE a eE E 260 A A NA RIS E 261 MTA HDENISG PROG orbitanta MTA IGNORE ERRORS 2 22 261 MTA INTERACTIVE mirc ce Ske Sed Got bue AA ae es Shack Ede dene 261 MTA MEM LIST i22 Ree reve A a e YT bide ee 261 N E Rom da teils 0 emacs 261 MTA MAX MTA MODE BINARY 2 2 ke RR EErEE ESE EEE oP EEP uA GR PIA E LUPOSE 261 edu e diae 262 Unde E ER Exi A MITA MODE TEXT is 262 MTA MSG PROC a CPI dee uhr UNES 202 MTA NOBLANK ied a ree TR E ELE PPE 262 MEA NOIGNOBE ERRORS cacas ten bau tee ace dan eee dead ia nee 263 MIA PRIV DISABLE 006 ees ceed edere 9 yp RE p ease ete PY EE a 263 MEA PRIV EN ABB PROC L
204. ing a Message Each message sent with ntasend must have a corresponding item list describing the message The entries in this item list specify the message s From and To addresses as well as input sources for the content of the message 237 Envelope and Header From Addresses The basic steps in sending a message with mtaSend are 1 Build an item list to pass to mtaSena To build an item list complete the following steps o Specify any special processing options such as MTA_BLANK or MTA_IGNORE_ERRORS o Specify the message s envelope From address with the MTA_USER item o Specify the message s To Cc and Bcc addresses with the MTA TO MTA CC and MTA_BCC items o Specify an initial message header in one of two ways l Specify an input source that supplies each of the initial message header lines MTA HDR FILE MTA HDR PROC ll Specify the content of individual message header lines with individual item codes MTA SUBJECT MTA HDR LINE o Specify the input sources for the message body with the MTA MSG FILE MTA MSG PROC items o Terminate the item list with an item code of value 0 VTA END LIST 2 Pass the item list to mtaSena 3 Check the return status from mtaSend For a description of all item codes and their return status values see Chapter 8 mtaSend Routine Specification To enqueue additional messages simply repeat these steps Envelope and Header From Addresses The
205. inter to receive any extended error message information In the event of an error associated with submitting the recipient to the MTA then the MTA may return additional information By providing this pointer that additional information may be obtained for diagnostic purposes This item code should be followed by two additional item codes 1 The address of a pointer to receive the address of the NULL terminated error text 2 The address of a size t to receive the length of that error text A value of NULL can be passed for the errmsg len argument The address is an active transport address that should also appear in a To header line This is the default interpretation of addresses added with mtaEnqueueTo Chapter 6 MTA SDK Reference 205 Additional Arguments const char errmsg size t errmsg len None Item Codes Continued MTA REASON MTA TO mtaEnqueueWrite Return Values Return Values Description 0 Normal successful completion MTA_BADARGS This value is returned for one of the following reasons 1 A NULL value was supplied for the ng ctx call argument 2 An invalid enqueue context was supplied for nq ctx 3 Arequired argument to an item code was NULL MTA NO If DO CONTEXT was specified then the supplied envelope To address does not match any envelope recipient address in the queued message represented by the supplied dequeue context Otherwise the MTA rejected the envelope recipi
206. inued EUE MTA DEBUG ENQUI MTA DEBUG MM MTA DEBUG OS MTA DEBUG SDK MTA ITEM LIST MTA INTERACTIVI 214 Messaging Server 6 2005Q1 MTA Developer s Reference mtaLog Description Normal successful completion A required argument to an item code was NULL Unable to initialize the MTA SDK Unable to read one or more configuration files Issue the following command for further information imsimta test rewrite Unable to initialize the MTA SDK Issue the following command for further information imsimta test rewrite Return Values Return Values 0 MTA BADARGS MTA FOPEN MTA NO An invalid item code was specified 215 MTA SDK Reference MTA NOSUCHITEM Example For normal use mtaInit 0 To select SDK diagnostics mtaInit MTA_DEBUG_SDK 0 Write diagnostic output to the channel s log file Syntax void mtaLog const char fmt Chapter 6 mtaLog Arguments Arguments Description fmt Pointer to a printf formatting string The string must be NULL terminated See your platform s C run time library documentation for information on the formatting substitutions accepted by printf Description Programs that wish to write diagnostic output should use mtaLog and mtaLogv These two routines ensure that diagnostic output is directed to the same output stream as other diagnostic information generated by the MTA SDK With one ex
207. ional call arguments 1 The address of a pointer to receive the address of the NULL terminated envelope ID 2 The address of a size t to receive the length of that envelope id A NULL value may be passed for the env id len argument Return the envelope recipient address last returned by mt aDequeueRecipientNext If that routine has not yet been called for the dequeue context then an MTA NO error code will be returned This item code must be followed by two additional call arguments 1 The address of a pointer to receive the address of the NULL terminated recipient address 2 The address of a size t to receive the length of that address A NULL value can be passed for the env to len argument mtaDequeuelnfo Additional Arguments ENV ID const char env id 5126 t env id len TO const char env to 5126 t env to len Messaging Server 6 2005Q1 MTA Developer s Reference Item Codes Continued MTA MTA 158 mtaDequeuelnfo Description Obtain the envelope From address for the message It is possible for this to be an empty string that is a string of zero length This is not uncommon and is mandated by Internet standards for automatically generated notification addresses Notifications must never be sent for messages with an empty envelope From address The MTA SDK adheres to this rule when generating any requested notification messages This item code must be foll
208. ional argument the maximum number of concurrent threads to permit By default the processing threads will have a stack whose size is sufficient for MTA SDK operations This is the size returned by the mtaStackSize routine To request a larger size use this item code to specify the desired size Note that specification of a smaller size is ignored mt aDequeueMessage will never use a stack size smaller than that returned by mtaStackSize This item code must be followed by one additional argument the minimum size in bytes for each thread s stack Additional Arguments mta_item_list_t item_list size_t attempts size_t seconds size_t threads size_t bytes mtaDequeueStart Item Codes Continued MTA_ITEM_LIST MTA_JBC_MAX_ATTEMPTS ERVAL ETRY INTI MTA JBC RI MTA THREAD MAX THREADS MTA THREAD STACK SIZE 174 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDequeueStart Item Codes Continued Additional Arguments Description MTA_THREAD_MAX_MESSAGES size_t messages The number of messages to allocate per processing thread The channel program will aim to run N processing threads where N is computed as follows N count of pending queued messages MTA THREAD MAX MESSAGES For example if there are 100 queued messages and MTA THREAD MAX MESSAGES has its default value of 20 messages then 5 processing threads are started This value does not control the tot
209. ivery attempt 16 The message header and body are read one line at a time with mtaDequeueLineNext When there are no more lines to read it returns a status of MTA EOF 17 Lines returned by mtabequeueLineNext might not be NULL terminated because the returned line pointer might point to a line in a read only memory mapped file 18 mtaDequeueMessageFinish is called once the message had been fully processed and the disposition of all its recipients set with mtaDequeueRecipientDisposition The message is not truly dequeued until this happens 19 Theroutine NotifyToStr converts a bitmap encoded set of RFC 1891 notification flags to an ASCII text string 20 TheUniqueName routine generates a unique string suitable for the use as a file name This is used to generate the unique portion of the file name This routine can be called concurrently by multiple threads and always generates a string unique amongst all processes and threads on the system Messaging Server 6 2005Q1 MTA Developer s Reference 70 Intermediate processing channels For information on how to run this sample program see Running Your Enqueue and Dequeue Programs on page 31 Output from the Complex Dequeue Example The output that follows shows the result of 100 queued messages processed with the program in Code Example 4 2 on page 63 tarting id 10 context 32360 tarting id 1 context 32390 16 93 Dequeue thread starting id 2 context 325e8 17
210. k list If all recipients have a permanent disposition all of the ones listed in the previous table except MTA DISP DEFERRED then any required non delivery notifications are generated and the message is permanently removed from the MTA queue If all recipients are to be deferred MTA DISP DEFERRED then no notifications are generated and the message is left in the queue for later delivery attempts If however some recipients have a permanent disposition and others are deferred then the following happens Chapter 4 Dequeuing Messages 53 The process message Routine a Notifications are generated for those recipients with permanent dispositions that require notifications b Anew message is enqueued for just the deferred recipients c Theoriginal message is removed from the queue Note that deferred messages will not be processed by this routine more than once unless another delivery attempt is made for the deferred message while the process is still running How long a message is deferred is configured as part of a channel s definition using the backoff channel keyword When finished the processing routine should return with a status code of zero 0 to indicate a success and an appropriate MTA status code in the event of an error If the processing routine returns before calling mtaDequeueFini sh then the message that was being handled is left in its queue for a subsequent processing attempt
211. kay and at least one input source was okay By default the message will not be sent if any of the To addresses are illegal such as bad syntax restricted unknown host or if any of the input sources proved to be bad such as could not open an input file The item address and item length fields are ignored for this item code MTA INTERACTIVE Do not ignore user to channel access checks when enqueuing mail This should in general be used by programs such as user agents that enqueue mail for users The item address and item length fields are ignored for this item code MTA ITEM LIST The mtaSend routine immediately begins processing the list of item descriptors pointed at by item address This new list will be used immediately any remaining items in the current list will be ignored The item length field is ignored for this item code MTA MAX TO Specify the maximum number of envelope To addresses per message copy If when the message is enqueued the number of envelope To addresses for the message exceeds this limit then the message will be broken into multiple copies each copy with no more than the specified number of envelope To addresses The item length field specifies the maximum number of envelope To addresses per message copy By default no limit is imposed MTA MODE BINARY Read subsequent input files as raw binary files This setting may be changed with the MTA MODE TEXT item code The default access mode i
212. ked with channel keywords such as thurman or inner or when using the SDK message decoding routine mtaDecodeMessage EUE None Enable diagnostic output from the low level queue processing routines used by the MTA SDK Use this diagnostic output when attempting to understand issues surrounding reading and processing of queued message files This diagnostic output will not help diagnose the selection of queued messages as that is handled by a separate process the MTA Job Controller Enabling this diagnostic output is equivalent to setting DEQUEUE DEBUG 1 in the MTA option file opt ion dat Chapter 6 MTA SDK Reference 3 Item Code MTA CHANNEL MTA DEBUG DEQUI Description Enable diagnostic output from the low level message enqueue routines used by the MTA SDK Enqueue diagnostics can be used to diagnose the address rewriting process destination channel selection header processing and other types of processing that occurs when a message is enqueued to the MTA Enabling this diagnostic output is equivalent to setting MM DEBUG 5 in the MTA option file Enable diagnostic output from the low level message enqueue routines used by the MTA SDK This item code must be followed by one additional call argument the debug level to use The debug level is an integer value in the range 0 20 Enqueue diagnostics may be used to diagnose the address rewriting process destination channel selection header processing
213. l be NULL terminated env_from_len The length in bytes of the envelope From string This length does not include any NULL terminator When a processing thread first begins running it sets the value referenced by ctx2 to NULL This assignment is made only once per thread and is done before the first call to the process_message routine Consequently on the first call to the process_message routine the following test is true ctx2 NULL That test will remain true until such time that the process_message routine itself changes the value by making an assignment to ctx2 As demonstrated in the following code fragment if the process_message routine needs to maintain state across calls to itself by the same processing thread it can allocate memory for a structure to store that state in and then save a pointer to that memory with ctx2 int process message void ctx2 void ctxl const char env from size t env from len struct our_state_t state state our_state_t ctx2 if state First call for this thread Allocate a structure in which to store the state information xy state our state t calloc 1 sizeof our state t Chapter 6 MTA SDK Reference 179 if state return MTA ABORT ctx2 void state Set any appropriate initial values for the state structure el For a sample process_message routine see Code Example 5 2 on page 6 process done
214. ld also be used by gateways that transfer the message to other mail systems capable of generating the necessary notification messages The message has been successfully processed for this recipient No further processing by this channel is needed for this recipient address however a relayed delivery status notification should be generated if delivery notification was requested for this recipient This disposition should be used by gateways that transfer the message to other mail systems incapable of generating the necessary notification messages Generate a postmaster non delivery notification for this recipient and for this recipient remove the message from the channel s queue This disposition is not intended for use by channels Instead it should be used by postmaster utilities that allow the postmaster to manually return mail messages Generate a timed out non delivery notification indicating that the message has been undeliverable for too long and no further delivery attempts will be made This disposition is not intended for use by channels Instead it is meant for use by the MTA return job that scans the MTA queues returning old undeliverable messages to their originators Chapter 6 MTA SDK Reference 7 Dispositions Delivery Status MTA DISP DELIVERED MTA DISP FAILED MTA DISP RELAYED MTA DISP RELAYED FOREIGN MTA DISP RETURN EDOUT MTA DISP TIMI This table lists the item codes for this routine and th
215. len int val Arguments Arguments Description opt ctx An option context created by mtaOptionStart A NULL value is permitted for this argument When a NULL is passed then no option value is returned name Name of the option to obtain the value for The length of this string should not exceed ALFA SIZE bytes This string must be NULL terminated if a value of zero is passed for 1en len Length in bytes not including any NULL terminator of the option name supplied with name If a value of zero is supplied then the option name string must be NULL terminated val Pointer to an integer of type int to receive the option s value If the option was not specified in the option file then the value referenced by this pointer will be left unchanged Description Use mtaOptionInt to retrieve the value of an option interpreting its value as an integer valued number If the option is specified in the option file and its value is a valid integer then its value will be returned using the val call argument If the option is not specified or its value does not correctly specify an integer then no value is returned and the memory pointed at by val is left unchanged The routine can be called with a NULL value for the opt ctx argument When this is done mtaOptionInt immediately returns with a status code of zero and no value is returned This routine does not provide an indication of whether or not the option was specified in t
216. ll leave the enqueue debug level set to 10 While the MTA DEBUG ENQUEUE item code sets it to 5 the subsequent MTA DEBUG MM item code changes the setting to 10 30 Messaging Server 6 2005001 MTA Developer s Reference Chapter 2 MTA SDK Programming Considerations This chapter describes procedures and run time instructions useful for programmers using the Sun Java System Messaging Server MTA SDK It includes the following topics e Running Your Enqueue and Dequeue Programs on page 31 Debugging Programs and Logging Diagnostics on page 33 e Required Privileges on page 33 e Compiling and Linking Programs on page 34 e Running Your Test Programs on page 34 e Preventing Mail Loops when Re enqueuing Mail on page 37 e Miscellaneous Programming Considerations on page 38 Running Your Enqueue and Dequeue Programs At run time when your program enqueues a message to or dequeues a message from the MTA the SDK must be able to determine the name of the MTA channel under which to perform the enqueue or dequeue If this name cannot be determined then the enqueue or dequeue operation will fail Consequently when calling mtaEnqueueStart or mtaDequeueStart a channel name can be specified Whether or not you need to specify this channel name depends upon the conditions under which your program runs While developing your program and 31 Running Your Enqueue and Dequeue Programs manually running
217. ller itself has logic to determine if more threads are needed in the currently running channel program or if it should create additional processes to run the same channel program To demonstrate the following code fragment shows pseudo code of the mtaDequeuestart loop threads_running 0 threads max MTA THREAD MAX THREADS attemtps MTA JBC MAX ATTEMPTS LOOP while threads running threads max Go to DONE if a shut down has been requested pending_messages Ask the Job Controller how many messsages there are to be processed If there are no pending messages then consider what to do next if pending messages 0 Continue to wait if attempts lt 0 go to DONE Decrement attempts and wait attempts attempts 1 go to SLEEP Reset the attempts counter attempts MTA_JBC_MAX_ATTEMPTS threads_needed Ask the Job Controller how many processing threads are needed Cannot run more then threads_max threads per process if threads needed gt threads max Chapter 6 MTA SDK Reference 1 threads needed threads max Create additional threads if needed if threads needed lt threads running Create threads_needed threads_running more threads threads_running threads_needed SLEEP Sleep for MTA JBC RETRY INTERVAL seconds a shut down request will cancel the sleep go to LOOP DONE Wait up to MTA THREAD WAIT TIMEOUT seconds for all proce
218. lternative to discarding the part it may be replaced with a part containing caller supplied data such as a warning message This replacement is achieved through the use of item codes 152 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDecodeMessagePartDelete Once mtaDecodeMessagePartDelete has been called the inspection routine will no longer be called for that message part As such calling the routine is final and cannot be undone short of cancelling the entire message decode operation itself for example by having the caller supplied read routine return an error or after mtaDecodeMessage completes cancelling the dequeue and enqueue operations with mtaDequeueMessageFinish and mtaEnqueueFinish The following table lists the item codes for this routine any additional item code arguments each item code requires and gives a description of each Description Specify the character set used for the message part for example us ascii iso 8859 1 This item code must be followed by two additional call arguments 1 The name of the character set 2 The length in bytes of that name If a value of zero is passed for the length then the name must be NULL terminated Specify the content disposition for the message part for example inline attachment filename a doc This disposition information will be placed in a Content disposition header line The item code must be followed by two additional call
219. ly enqueue multiple messages each message represented by its own enqueue context Indeed multiple threads may simultaneously enqueue one or more messages per thread The only requirement is that a specific enqueue context not be simultaneously used by two or more threads In the event that the SDK detects simultaneous usages it returns the MTA THREAD error Enqueuing Dequeued Mail If a message being enqueued is the result of dequeuing a message then all envelope fields can automatically be carried over from the old message to the new message Both per message fields such as envelope IDs and per recipient fields such as delivery receipt requests can be preserved This preservation is achieved by supplying the associated dequeue context to the routines mtaEnqueueStart or mtaEnqueueTo or both Supplying the dequeue context to mtaEnqueueStart preserves per message envelope fields while supplying the dequeue context to mtaEnqueueTo preserves the per recipient fields for the specified envelope recipient For information on message dequeuing and message dequeue contexts see Dequeuing Messages on page 25 Dequeuing Messages Messages stored in the MTA message queues are removed from their queues by dequeuing them This is typically done by channel programs see Channel Programs and Message Queuing on page 21 When a message is dequeued it is literally removed from the MTA message queues and as far as the MTA is conce
220. ly query or set MTA states or parse message structures such as lists of RFC 822 addresses The Callable Send facility described in Chapter 5 and Chapter 6 and used only for originating mail from the local host can be used simultaneously with the MTA SDK This chapter contains the following topics e Channel Programs and Message Queuing on page 21 e Managing Multiple Threads Contexts on page 22 e Enqueuing Messages on page 22 e Dequeuing Messages on page 25 e String valued Call Arguments on page 27 e Item Codes and Item Lists on page 28 Channel Programs and Message Queuing Message enqueuing and dequeuing are generally done by channel programs also referred to simply as channels There are two types of channel programs master channel that dequeue messages and channels sometimes referred to as slave channels that enqueue messages Each MTA channel has its own message queue referred to as a channel queue Channel programs may also perform intermediate 21 Managing Multiple Threads Contexts roles by dequeuing messages from one message queue and re enqueuing them to another while typically processing the message at the same time For example the message processing might be to convert the message body from one format to another Managing Multiple Threads Contexts A number of SDK operations require multiple sequential calls to the SDK routines To manage this the SDK provides the caller with
221. m and a length of zero for env rom len or supply a value of NULL for env from and any value for env from len When using a dequeue context to supply the envelope From address simply supply a value of NULL and zero for respectively the env from and env from len call arguments Be sure to also supply the dequeue context with the MTA DQ CONTEXT item code For example ires mtaEnqueueStart amp nq NULL 0 MTA DQ CONTEXT dq 0 Chapter 6 MTA SDK Reference 195 If the submitted message lacks a From header line then the address supplied as the envelope From address will also be used to generate a From header line This is the reason why mtaEnqueueStart allows an RFC 2822 compliant address to be supplied for the envelope From address When placing the supplied address into the envelope the MTA reduces it to an RFC 2821 compliant address for example removes any RFC 2822 phrases or comment fields When submitting a message the MTA requires a source channel to associate with the enqueue operation By default the name of the source channel will be derived from the PMDF CHANNEL environment variable However this may be overridden one of two ways by supplying a dequeue context with the MTA DQ CONTEXT item code or by explicitly specifying the channel name with the MTA CHANNEL item code Use of a dequeue context implicitly specifies the source channel name to be the name of the channel associated with the dequeue conte
222. mail systems such as SMS and X 400 The second mode of operation allows the message to be rewritten after inspection The output destination for this rewriting may be either the MTA channel queues or an arbitrary destination via a caller supplied output routine 85 Usage Modes for mtaDecodeMessage During the inspection process in this second usage mode individual atomic message parts may be discarded or replaced with text This operational mode is primarily of use to intermediate processing channels which need to scan message content or perform content conversions For example virus scanners and encryption software A Simple Decoding Example on page 89 illustrates the first usage mode while A Simple Virus Scanner Example on page 95 the second For the first usage mode the calling routine must supply the following items 1 Aninput source for the message 2 Aninspection routine which will be passed each atomic message part of the parsed and decoded message For the second usage mode the calling routine must supply the same two items as listed for the first usage mode and in addition a third item must be supplied 3 Anoutput destination to direct the resulting message to The input source can be either a queued message file represented by a dequeue context or it can be provided by a caller supplied input routine Use the former when processing queued messages and the latter when processing data from disk files data strea
223. me ea gw ad edn ween ERE MTA ENC BASBBS ocio DES MEA ENC BINEIENX ENG REIR Y n rE E MT ENC COMPRESSED 349664 ccc eee eee MIA ENC COMPRESSED BINARY ocio RR Eee n MTA ENC COMPRESSED UUENCODE MTA_ENC_HEXADECIMAL eeeeee mn MEA ENC NONRB 1 222 mew ke eec ERerbrCO HR ERR MTA ENC PATHWORKS 3 35 65 ch oie tinh ete MTA_ENC_ QUOTED PRINTABLE 20 00 ccc e I RR rem UNKNOWN cuotas eins teh ee Pia Yd MEA ENC VUENCODE oso sls id aaa anaes E EEG ERA MTA END LIST cuco roda MTA ENV FROM MTA ENV 2 MEA FRAGMENT BLOCKS senecrkermnc eene em EEEE EERE aA Examples of Using imfa5end o noni ias Example 1 Sending a Simple Message 00 0c eee e ees Example T 6701001 aii brian e eR Rr ees Example 2 Specifying an Initial Message Header Example 2 Input Ele cocida Example OutpUE Example 3 Sending a Message to Multiple Recipients Example 3 Output ied RR Re pner REIR EET Example 4 Using an Input Procedure to Generate the Message Body Chapter 8 mtaSend Routine Specification intasendl A DERE m AM aa e mal mma ke ALGUIEN eeter AA E dae Ese eda ter Descriptor Fields aie kepi ta s RET ERG cee RERO ehe Pepe U 0860 soria aldea NPA ADR NOSTATUS 120 e a iaa MTA ADR STATUS a eis qued uerb Re UR MTA BCC 09006 bod lad Rem iaa Messag
224. messages and more specifically is doing intermediate processing that leaves the envelope recipient addresses unchanged then special rewrite rules must be used to prevent a message loop in that the channel just enqueues the mail back to itself For directions on how to prevent a message loop see Preventing Mail Loops when Re enqueuing Mail on page 37 For other specific examples of rewrite rules see the examples in Preventing Mail Loops when Re enqueuing Mail on page 37 Manually Running Your Test Programs Perform the following tasks 1 Ifthe program does not explicitly set the channel name then you must define the PMDF CHANNEL environment variable The value of that variable must be the name of your channel The following example shows how to set the PMDF CHANNEL environment variable PMDF CHANNEL x test export PMDF CHANNEL For further information see Running Your Enqueue and Dequeue Programs on page 31 2 Ensure that any environment variables required to run a program linked against the MTA SDK are defined See Compiling and Linking Programs on page 34 for additional information 3 Under some circumstances it might be useful to comment out the master command line in the job controller site file That way you can enqueue mail to your test channel but not have the Job Controller actually run your channel program 4 When repeatedly testing your channel program it is often necessary to restart the Job Contr
225. mful media type of s strlen buf 2 buf 1 else i sprintf msg The content of this message part has been removed An It contained a potentially harmful file named s buf return mtaDecodeMessagePartDelete dctx MTA REASON msg i MTA DECODE CTYPE text 4 Messaging Server 6 2005Q1 MTA Developer s Reference 100 A Simple Virus Scanner Example Code Example 5 2 Decoding MIME Messages Complex Example Continued MTA DECODE CSUBTYPE plain 5 MTA DECODE CCHARSET us ascii 8 MTA DECODE CDISP inline 6 MTA DECODE CLANG en 2 0 else Keep the part See explanatory comment 12 return mtaDecodeMessagePartCopy dctx 0 is bad mime type See if the part s media type is in our x bad MIME content types for example application vbscript See explanatory comment 13 static int is bad mime type our options t options mta decode t dctx char buf size t maxbuflen const char csubtype ctype size t i lenl len2 char ptr Sanity checks up if options options bmt len loptions bad mime types 0 dctx return 0 Get the MIME content type ctype mtaDecodeMessageInfoString dctx MTA DECODE CTYPE NULL amp lenl csubtype mtaDecodeMessageInfoString dctx MTA DECODE CSUBTYPE NULL amp len2 Build the string lt 0x01 gt type subtype lt 0x01 gt lt 0x00 gt ptr buf 6 char 0x01
226. mith e MTA ADDR DOMAIN In the example the domain part is email siroe com For example to select just the local and domain parts use the following value for the elements argument MTA ADDR LOCAL MTA ADDR DOMAIN When a value of zero is supplied for elements the following default bitmask is assumed MTA ADDR ROUTE MTA ADDR LOCAL MTA ADDR DOMAIN Address Argument This routine returns a pointer to the retrieved address and not the address itself This pointer is to a buffer within the address context Each time the routine is called with the same address context that buffer is overwritten Therefore care must be taken when specifying the address argument The following code example correctly specifies how the argument should be used when multiple calls are involved mtaAddressGetN adr ctx 0 amp ptr NULL MTA ADDR LOCAL strcpy buf ptr strcat buf 6 mtaAddressGetN adr ctx 0 amp ptr NULL MTA ADDR DOMAIN strcat buf ptr Alternately it could also be coded as shown in the following code fragment mtaAddressGetN adr ctx 0 amp ptr NULL MTA ADDR LOCAL MTA ADDR DOMAIN strcpy buf ptr mtaAddressGetN 120 Messaging Server 6 2005Q1 MTA Developer s Reference mtaAddressParse However since the pointer points to the same buffer for each call and is overwritten at each call it would be incorrect to code it as shown in the following code example mtaAddressGetN adr ctx
227. ms or other arbitrary input sources Since the parser and decoder require only a single sequential pass over its input data it is possible to stream data to mtaDecodeMessage The output destination can be a message being enqueued and represented either by an enqueue context or by a caller supplied output routine Use an enqueue context when submitting the message to the MTA In all other cases use a caller supplied output routine The following are some common usage cases and their associated input sources and output destinations Send to the MTA slave channel For this case a caller supplied routine accepts incoming messages from a source outside of the MTA and then enqueues it to the MTA The caller supplied input routine is used in conjunction with an enqueue context as the output source Doing a MIME parse and decode isn t usually called for in this case However specialized services might be constructed this way For instance a custom server that accepts MIME formatted messages and strips a control attachment before submitting the remainder of the message to the MTA Messaging Server 6 2005Q1 MTA Developer s Reference 86 The Input Source Anintermediate processing channel For this case an example is a virus scanner that scans queued mail messages re enqueuing them to the MTA for delivery In this case a dequeue context is used as the input source and an enqueue context as the output source Send from the
228. msg server base examples mtasdk Note that certain lines of code have numbered comments immediately preceding them of the format This generates output line N where N corresponds to the numbers found next to certain output lines in the sample output Refer to Running Your Test Programs on page 34 for information on how to run the sample program Code Example 3 1 Enqueuing a Message hello world c A simple Hello World enqueue example include lt stdio h gt include lt stdlib h gt include mtasdk h mta nq t ctx NULL static void quit void define CHECK x if x quit void main int 8200 const char argv char buf 100 Initialize the SDK CHECK mtaInit 0 Start a new message From postmaster This generates output line 1 CHECK mtaEnqueueStart amp ctx mtaPostmasterAddress NULL NULL 0 0 0 Enqueue the message to argv 1 or root This generates output line 2 CHECK mtaEnqueueTo ctx argv 1 argv 1 root 0 0 Date header line This generates output line 3 CHECK mtaEnqueueWriteLine ctx Date 0 mtaDateTime buf NULL sizeof buf 0 0 NULL Subject header line This generates output line 4 CHECK mtaEnqueueWriteLine ctx Subject _ FILE 0 NULL Blank line ending the header starting the message body This generates output line 5 CHECK mtaEnqueueWriteLine ctx
229. mtaDequeueMessageFinish dq MTA ABORT 0 And return our error status return ires Chapter 5 Decoding Messages 9 A Simple Virus Scanner Example Code Example 5 2 Decoding MIME Messages Complex Example Continued fundef CHECK decode inspect This is the routine that inspects each m message part deciding whether to accept or reject it See explanatory comment 10 static int decode inspect void ctx mta decode t dctx int data type const char data Size t data len char buf BIGALFA SIZE 2 10 int i our options t options our options t ctx See if the part has 0 1 A bad MIME content type 2 A bad file name extension in the deprecated NAME content type parameter or 3 A bad file name extension in the FILENAME content disposition parameter IN i 0 if i is bad mime type ctx dctx buf sizeof buf is_bad_file_type ctx mtaDecodeMessageInfoParams dctx MTA DECODE CTYPE PARAMS NULL NAME buf sizeof buf is bad file type ctx mtaDecodeMessageInfoParams dctx DECODE 60185 PARAMS NULL FILENAME buf sizeof buf char msg BIGALFA SIZE 4 10 Replace this part with a text message indicating that the part s content has been deleted See explanatory comment 11 T 1 1 sprintf msg The content of this message part has been removed n It contained a potentially har
230. must be called in order to successfully enqueue a Chapter 3 Enqueuing Messages 7 message These routines are mtaEnqueueStart mtaEnqueueTo and mtaEnqueueF inish To determine at which point a routine may be called start in the leftmost column and work towards the rightmost column Any routine whose line segment lies in the first leftmost column may be called first Any routine whose line segment falls in the second column may next be called after which any routine whose line segment falls in the third column may be called and so forth When more than one routine appears in the same column any or all of those routines may be called in any order Progression from left to right across the columns is mandated by the need to call the required routines Of the required routines only mtaEnqueueTo may be called multiple times for a given message Figure 3 1 Calling Order Dependency for Message Enqueue Routines mtaInit mtaEnqueueStart mtaEnqueueTo mtaEnqueueWrite mtaEnqueueWriteLine mtaEnqueueCopyMessage mtaEnqueueInfo mtaEnqueueError mtaEnqueueFinish 0000 Order Dependencies 48 Messaging Server 6 2005001 MTA Developer s Reference Chapter 4 Dequeuing Messages Once enqueued to the MTA messages are processed using the SDK dequeue routines These routines provide channel programs and MTA utilities with programmatic access to queued messages With these ro
231. must be terminated with an integer argument with value 0 Description Information associated with an ongoing message dequeue may be obtained with mt aDequeueInfo The information to obtain is specified through the use of item codes NOTE The pointers returned by mtaDequeueInfo are only valid during the life of the dequeue context Once the dequeue has been completed for that particular message the pointers are no longer valid Item Codes Additional Arguments Description MTA CHANNEL const char channel Obtain the name of the channel for which messages z are being dequeued The channel name will be NULL terminated This item code must be followed by two additional call arguments 1 the address of a pointer to receive the address of the NULL terminated channel name 2 The address of a size t to receive the length of the channel name A NULL value may be passed for the channel len argument 156 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDequeuelnfo Description Additional Arguments Item Codes Continued Return the envelope delivery flags for either the entire message or for a particular recipient If called before the first call to mtaDequeueRecipientNext then the delivery flags for the entire message are returned If called after the first call to mtaDequeueRecipientNext then the delivery flags are returned for the most recently reported envelope recipient a
232. n this step could be almost anything including possibly enqueuing a new message or messages with the MTA SDK The details of this step will depend upon the purpose of the program itself Programs needing to do MIME parsing should consider using the mtaDecodeMessage routine For further information about message processing threads and caller supplied message processing routines see Processing the Message Queue on page 60 4 Report the disposition of each envelope recipient with per recipient calls to mtaDequeueRecipientDisposition or a single call to mtaDequeueMessageFinish with the MTA DISP item code The following table lists the valid recipient dispositions Symbolic Name Description MTA DISP DEFERRED Unable to process this recipient address Processing has failed owing to a temporary problem such as the network is down a remote host is unreachable or a mailbox is busy Retry delivery for this recipient at a later time as determined by the configuration of the channel MTA DISP DELIVERED Recipient address successfully delivered Generate a delivery status notification if required Messaging Server 6 2005Q1 MTA Developer s Reference 52 Caller Supplied Processing Routine Description Unable to process this recipient address Processing has failed owing to a permanent problem such as an invalid recipient address or recipient over quota No further delivery attempts should be made for this recipient Gen
233. ng the MIME Internet messaging format Additionally these facilities can convert messages with other formats to MIME for example text parts with BINHEX or UUENCODE data the RFC 1154 format and many other proprietary formats The mtaDecodeMessage routine provides access to these facilities parsing either a queued message or a message from an arbitrary source such as a disk file or a data stream There are two usage modes for mt aDecodeMessage In the first mode messages are simply parsed any encoded content decoded and each resulting atomic message part presented to an inspection routine This mode of usage is primarily of use to channels that interface the MTA to non Internet mail systems such as SMS and X 400 The second mode of operation allows the message to be rewritten after inspection by an output routine The output destination for this rewriting may be either the MTA channel queues or an arbitrary destination via a caller supplied output routine mtaDecodeMessage 136 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDecodeMessage During the inspection process in this second usage mode individual atomic message parts may be discarded or replaced with text This operational mode is primarily of use to intermediate processing channels that need to scan message content or perform content conversions for example virus scanners and encryption software Decoding MIME Messages on page 89 illustrates t
234. ngle threaded Return Values None Example mtaDone mtaEnqueueCopyMessage Copy a queued message to a new message being enqueued Chapter 6 MTA SDK Reference 3 mtaEnqueueCopyMessage Syntax int mtaEnqueueCopyMessage mta nq t nq ctx mta dq t dq ctx int rewind Arguments Arguments Description nq ctx Message submission to copy the message data to ng ct x must be an enqueue context created by mtaEnqueueStart dq_ctx Queued message to copy the message data from Must be a a dequeue context created by mtaDequeueStart rewind Supply a value of 1 to move the read point in the queued message file to the start of the message before commencing the copy operation Supply a value of zero to leave the message read point unchanged before copying Description Intermediate processing channels often need to copy verbatim a message from a channel queue to a new message being enqueued That is intermediate processing channels often re enqueue an existing queued message This verbatim copy can be accomplished with mt aEnqueueCopyMessage Using this routine is significantly faster than using mt aDequeueLineNext and mtaEnqueueWriteLine in a read and write loop When mt aEnqueueCopyMessage is called the copy begins at the current read point of the queued message file associated with the supplied dequeue context dq ctx The message file from that point to its end is copied to the new message bein
235. ngth in bytes of the returned channel name This length does not include the NULL terminator that terminates the channel name channel len max The maximum size in bytes of the buffer pointed at by the channel argument Description A running program can discover its channel name with this routine The channel name is typically set using the CHANNEL environment variable Return Values In the event of an error the routine returns NULL The error status code is set in mta errno Error Status Codes Description TA BADARGS A NULL value passed for the channel argument TA NO Unable to determine the channel name from the runtime environment TA STRTRUERR Channel buffer too small to receive the channel name The buffer must be at least CHANLENGTH 1 bytes long Example The following code fragment uses this routine to print the channel name char buf CHANLENGTH41 printf Channel name s n mtaChannelGetName buf NULL sizeof buf mtaChannelGetName 128 Messaging Server 6 2005Q1 MTA Developer s Reference mtaChannelToHost mtaChannelToHost Determine the host name associated with a channel Syntax const char mtaChannelToHost char host 5126 t host len int item code Arguments Arguments Description host A pointer to receive the host name The host name will be NULL terminated NULL can be passed for this call argument host len An optional pointer to a
236. nish Inthe event of an error the message submission should be cancelled with mtaEnqueueFinish mtaDecodeMessage will write the entire message header and content There is no need for the caller to write anything to the message s header or content Caller Supplied Output Routine To use a caller supplied output routine specify the MTA DECODE PROC for the output type call argument and pass the address of the output routine as the output argument This code fragment shows the syntax of a caller supplied output routine int output routine void EGU mta_decode_t dctx const char line size t line len The following table lists the arguments for a caller supplied output routine and gives a description of each Arguments Description GUX The caller supplied private context passed as ct x to mtaDecodeMessage dctx A decode context created by mt aDecodeMessage This decode context should be used with calls to the other decode routines requiring a decode context This context is automatically disposed of by mtaDecodeMessage line Pointer to a line of the message to output This line is not NULL terminated The line will also lack any carriage return or line feed record terminators line len The length in bytes of the message line to output A length of 0 indicates a blank line The maximum line length presented will be BIGALFA SIZE bytes 1024 bytes Chapter 6 MTA SDK Reference 1
237. nnel queues or while reading from a temporary file TA NO Error terminating the message temporary file there appears to be insufficient disk space to write the message copies or there is a problem with a configured content scanner for example a virus or spam filter TA NOSUCHITEM An invalid item code was supplied TA ORDER The call was made out of order Either no envelope recipient addresses have been specified or no message content has been provided TA THREAD Simultaneous use of the enqueue context by two different threads was detected NOTE In case of an error the MTA_REASON item code can be used to receive extended error message information As shown in the preceding table in the case of an error the MTA REASON item code can be used to receive extended error message information Example See A Simple Example of Enqueuing a Message on page 43 mtaEnqueuelnfo Obtain information associated with an ongoing message enqueue Chapter 6 MTA SDK Reference 9 mtaEnqueuelnfo Syntax int mtaEnqueueInfo mta nq t nq ctx int item code int mtaEnqueueInfo mta nq t nq ctx Arguments Arguments Description nq ctx An enqueue context created by mtaEnqueueStart item_code An optional list of item codes See the description section that follows for a list of item codes The list must be terminated with an integer argument with value 0 Description Information associated with an on
238. not specified the name of the channel to process queued messages for is taken from the PMDF CHANNEL environment EL Item Codes MTA CHANNI variable Chapter 6 MTA SDK Reference 173 Description Specify a pointer to an item list array The item list array must be terminated with a final array entry with an item code value of zero For further information on item list usage see Item Codes and Item Lists on page 28 Specify the maximum number of contiguous attempts that will be made to sleep and then re query the Job Controller for work after being told by the Job Controller that there are no more messages to process The default value for this setting is 5 attempts If an attempt succeeds in providing additional work the count of attempts is reset to zero The duration of each sleep may be specified with the MTA JBC RETRY INTERVAL item code This item code must be followed by an additional argument the maximum number of contiguous attempts to make Set the number of seconds mtaDequeueMessage sleeps before again querying the Job Controller for additional work When not specified a value of 10 seconds is used This item code must be followed by one additional argument the number of seconds to sleep for Specify the maximum number of processing threads to run concurrently If not specified then a limit of 20 threads is assumed This item code must be followed by one addit
239. not the option context pointer is NULL If however the existence of an option file is mandatory then a program can detect that the file does not exist by seeing if the returned value for the option context pointer is NULL as shown in the code example section that follows If an explicit option file path is specified with the path call argument then the path can be a relative file path or an absolute file path File paths can be prefixed with any of the symbolic MTA directory names specified in the imta tailor file For example the entry shown in the following code fragment specifies a file named mnsc gateway cnf located in the nmsc subdirectory of the MTA configuration directory Note that a colon separates the symbolic name from the remainder of the path IMTA TABLE mmsc mmsc gateway cnf If no file path is specified then the file specified with the PMDF CHANNEL OPTION environment variable will be opened and read That environment variable is established by the Job Controller for the channel programs that it runs It will always have the following format IMTA TABLE channel name option where channel name is the name of the channel being run The following example demonstrates how the environment variable settings are effected for tcp 1ocal channel PMDF CHANNEL tcp local PMDF CHANNEL OPTION IMTA TABLE tcp local option mtaOptionStart 224 Messaging Server 6 2005Q1 MTA Developer s Reference mtaOptionString Return
240. nput routine along with the DECODE PROC item code to mtaDecodeMessage In Code Example 5 1 on page 89 the caller supplied routine s name is decode read Chapter 5 Decoding Messages 7 The Inspection Routine When using a caller supplied input routine each block of data returned by the routine must be a single line of the message This is the default expectation of mtaDecodeMessage and corresponds to the MTA TERM NONE item code If instead the MTA TERM CR _CRLF _LF or _LFCR item code are specified then the block of data need not correspond to a single complete line of message data it may be a portion of a line multiple lines or even the entire message On each successful call the input routine should return a status code of zero MTA OK When there is no more message data to provide then the input routine should return MTA_EOF The call that returns the last byte of data should return zero itis the subsequent call that must return MTA_EOF In the event of an error the input routine should return a non zero status code other than MTA_EOF for example NO This terminates the message parsing process and mtaDecodeMessage returns an error The Inspection Routine Whenever mtaDecodeMessage is called an inspection routine must be supplied by the caller In Code Example 5 1 on page 89 the inspection routine s name is decode inspect As the message is parsed and decoded mtaDecodeMes
241. nput source This blank line will automatically be supplied when the MTA BLANK item code is specified in the item list The MODE and ENC items control the access mode and encodings applied to message body input sources These items set the current access mode and encoding to be applied to all subsequent input sources that appear in the item list The default access mode is MTA MODE TEXT which uses text mode access The default encoding is ENC UNKNOWN which results in no encoding of the data The binary access mode will not be applied to input procedures The access mode and encoding item codes do not apply to input sources for an initial message header which is always accessed using the default access mode and never encoded Input procedures use the following calling format ssize t proc const char bufadr where const char bufadr is the address of pointer to the starting memory location of the next piece of input data The return value is ssize t which gives the length of the input data A value that is equal to or greater than zero 0 indicates success A value of minus one 1 indicates that there is no further data to return EOF Any other negative value indicates an error for which processing should be aborted The procedure will be repeatedly called until a negative value is returned which indicates all input data has been retrieved or an error occurred Messaging Server 6 2005Q1 MT
242. nsions The sample program replaces the attachment with a text attachment indicating the content has been deleted Received from 129 153 12 22 129 153 12 22 by frodo siroe com Sun Java System Messaging Server 6 200402 built Apr 7 2003 with SMTP id lt 0HD70010230YDA00 frodo siroe com gt for for sue sesta com Fri 11 Apr 2003 13 03 23 0700 PDT Date Fri 11 Apr 2003 13 03 08 0 From sue sesta com Subject test message Message id lt 0HD7001033P1DA00 frodo siroe com gt Content type multipart mixed boundary BoundaryMarke BoundaryMarker Content type text plain charset us ascii Content disposition inline This is a test message BoundaryMarker Content type application octet stream Content disposition attachment filename trojan horse vbs Content transfer encoding base64 IyFQUwOxMDAgMTAwIGlvdmVObyAzMDAgMzAwIGxpbmVObyBzdHJva2UKc2hvd3Bh Z2UK BoundaryMarker Messaging Server 6 2005Q1 MTA Developer s Reference 106 A Simple Virus Scanner Example Explanatory Text for Numbered Comments 1 TheMTA SDK is explicitly initialized This call is not really necessary as the MTA SDK will implicitly initialize itself when mtaDequeueStart is called However for debugging purposes it can be useful to make this call at the start of a program so that an initialization failure will show clearly in the diagnostic output If the call is omitted initialization failure will be less obvi
243. nst char fmt va list ap Arguments Arguments Description fmt Pointer to a printf formatting string The string must be NULL terminated See your platform s C run time library documentation for information on the formatting substitutions accepted by printf ap A va_list structure as defined by the system stdarg h header file Description The mtaLogv routine is provided for programs that either need to provide a diagnostic interface accepting a va list argument or want to provide some generalization of mtaLog Use of mtaLogv ensures that diagnostic output is directed to the same output stream as other diagnostic information generated by the MTA SDK With one exception consider a call to mtaLogv as being identical to calling the C run time library routine vprintf The call arguments for the two routines are identical including the formatting argument fmt The single exception is that unlike vprintf a call to mtaLogv always produces a single line of output to the channel s log file Consequently do not attempt to write either partial or multiple lines with a single call to mtaLogv Do not include a terminating line feed or other record terminator in the output That is do not put a n at the end of the formatting string Return Values None Example The following code fragment demonstrates a way to provide a generalization of mtaLog using mtaLogv finclude lt stdarg h gt voi
244. nt of an error the input routine should return a non zero status code other than MTA_EOF such as MTA NO This will terminate the message parsing process and mtaDecodeMessage will return an error NOTE By default each block of data must be a single line of the message This corresponds to the MTA TERM NONE item code If the MTA TERM CR MTA TERM CRLF MTA TERM LF OrMTA TERM LFCRitem code is specified then the block of data need not correspond to a single complete line of message data It may be a portion of a line multiple lines or even the entire message See Item Codes on page 143 for information about mtaDecodeMessage item codes Enqueue Context The parsed message may be output either as a message enqueue or written to an arbitrary destination via a caller supplied output routine When using a message enqueue context observe the following points e Specify MTA DECODE for the output type call argument mtaDecodeMessage 140 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDecodeMessage e Pass the enqueue context from mtaEnqueueStart as the output e Specification of the message s recipient list must have already been completed with mtaEnqueueTo before calling mtaDecodeMessage e ntaEnqueueFinish must not yet have been called for the enqueue context e After the call to ntabecodeMessage has completed successfully complete the message enqueue with mtaEnqueueFi
245. nvelope recipient addresses which are Bcc recipients the MTA SDK will automatically generate N 1 message copies one copy for each of the Bcc recipients and an additional copy for the remaining non Bcc recipients Each copy for a Bcc recipient will only disclose that Bcc recipient in the message s header The message copy for all of the non Bcc recipients will disclose none of the Bcc recipients in its header An address may be added as only an active transport address without addition to any header line This is done with the MTA ENV TO item code This item code should be used by intermediate processing channels that copy verbatim the outer message header from the old message to the new which prevents duplication of addresses in the new message s header When an active transport address is added to a message it is possible that the MTA will reject the address For example the address can be rejected when there is a mapping table such as the SEND ACCESS mapping table When an address is rejected by the MTA extended error text is made available by the MTA This extended information can be captured through use of the MTA_REASON item code The following table lists the item codes for this routine their additional arguments and gives a description of each mtaEnqueueTo Item Codes Additional Arguments Description None The address is an active transport address that should also appear in a Bcc header line The address will b
246. nversion channel which after scanning or converting a message re enqueues it back to the MTA for further routing or delivery Such channels should do the following e Preserve Envelope Information e Use MTA_ENV_TO e Use Rewrite Rules to Prevent Message Loops The sample code Intermediate Channel Example on page 73 illustrates the SDK usage required to effect the first two preceding points Chapter 4 Dequeuing Messages 1 Intermediate processing channels Preserve Envelope Information All queued messages have envelope fields which are unique to the message For instance a message will have the RFC 1891 envelope ID that was either assigned by the MTA when the message was first enqueued or was specified by a remote MTA and transmitted over SMTP The same applies to the RFC 1891 original recipient address fields that specify the original form of each of the message s envelope recipient addresses Furthermore there may be other envelope fields which have non default settings such as notification handling flags Whenever possible this information should be preserved as the message flows from MTA channel to MTA channel In order to preserve this information it must be copied from the message being dequeued to the new message being enqueued This copying process is best done using the MTA DQ CONTEXT item code in conjunction with the mtaEnqueueStart and mtaEnqueueTo routines When used with the former it causes per message
247. of MTA SDK error codes These descriptions are intended solely for use in fine grained diagnostic output They are not intended for reading by end users of programs written using the MTA SDK Return Values A pointer to a NULL terminated string containing the error code description Example ires mtaEnqueueStart amp nq from 0 0 if ires printf mtaEnqueueStart returned d s n ires mtaStrError ires 0 mtaUniqueString Generate a system wide unique string 230 Messaging Server 6 2005Q1 MTA Developer s Reference mtaVersionMajor Syntax const char mtaUniqueString char buf size t len size t max len Arguments Arguments Description buf A pointer to a buffer to receive the NULL terminated unique string The buffer should be at least 20 bytes long len An optional pointer to a size t to receive the length in bytes of the returned unique string This length does not include the NULL terminator that terminates the returned unique string A value of NULL can be passed for this call argument len max The maximum size in bytes of the buffer pointed at by buf Description The mtaUniqueString routine may be used to generate a system wide unique string The strings generated are suitable for use as MIME boundary markers and file names On a successful completion the unique string is stored in the buffer pointed at by the buf argument Additionally the value of the buf argument is
248. of a queued message file was made before first reading the message s entire recipient list Or an attempt was made to write the content of a message being submitted before first specifying the message s recipients Refer to the call order diagrams in for further details The message being submitted cannot be enqueued its size exceeds a site configured size limit Such limits are configured with a variety of options including the MTA options BLOCK LIMIT and LINE LIMIT as well as the channel keywords blocklimit and linelimit The supplied buffer was not large enough to receive the result string The result string was truncated to fit The result string is nonetheless NULL terminated The supplied buffer was not larger enough to receive the result string Truncating the result is not meaningful or has potential for causing problems or both Alternatively a supplied string was too long Threading error detected Specifically the MTA SDK detected the simultaneous use of a single SDK context by two or more processing threads This is not permitted This error code is not presently used by the MTA SDK In general it is used to indicate a timeout related error Appendix A Error Status Codes Summary Numeric Value 14 1 5 16 17 18 19 20 Return Code MTA_NOSUCHITEM MTA_ORDER MTA_SIZE TA_STRTRU TA_STRTRUERR TA_THREAD TA_TIMEDOUT 268 Messaging Server 6 2005001 MTA Developer s
249. oller before each manual test run Otherwise the Job Controller will hand off messages to your program on the first manual run but not the second manual run The Job Controller will think that retries of the messages need to be delayed by several hours By restarting the Job Controller you cause it to forget which queued messages are to be deferred Thus when you run your channel again it will be presented with all of the queued messages Messaging Server 6 2005Q1 MTA Developer s Reference 36 Preventing Mail Loops when Re enqueuing Mail Preventing Mail Loops when Re enqueuing Mail This section shows how to add a new rewrite rule to prevent a message loop from happening if the program is doing intermediate processing that leaves the envelope recipient addresses unchanged Otherwise the channel would just enqueue the mail back to itself For discussion purposes suppose that the channel is to provide intermediate processing for mail addressed to user siroe com Further the imta cnf file has the following rewrite rule for siroe com siroe com U siroe com For example as shown in the code example that follows assume that the intermediate processing channel s name is xloop test Near the bottom of the imta cnf file with other channel definitions you would see the following definition xloop test x looptest daemon Then as shown in the following example a new rewrite rule for siroe comneeds to be added to the
250. ope recipient must be set either by repeated calls to mtaDequeueRecipientDisposition or by means of the MTA DISP item code for mtaDequeueMessageFinish For the former a call should be made for each 162 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDequeueMessageFinish envelope recipient address For the latter the disposition set with MTA_DISP applies to all envelope recipients overriding any previous settings made with mtaDequeueRecipientDisposition It is important that the dispositions be set correctly because they influence whether or not the message is deleted from the channel s queue by mt aDequeueMessageF inish Incorrectly setting the dispositions can lead to duplicate message delivery or worse yet lost mail To complete processing of a queued message call mt aDequeueMessageFinish Upon being called the routine performs one of three possible actions e If all recipients have a disposition indicating successful processing or a permanent failure then the underlying message file is deleted from the channel s queue and any necessary notification messages are sent This corresponds to the dispositions MTA_DISP_DELIVERED MTA_DISP_FAILED MTA_DISP_RELAYED MTA_DISP_RELAYED_FOREIGN MTA_DISP_RETURN and MTA_DISP_TIMEDOUT e If all recipients have a disposition indicating a temporary processing problem or if the MTA_ABORT item code is specified then the message file is left in the ch
251. ous The failure will still be noted in the diagnostic output but it will be obscured through the routine call that triggered implicit initialization 2 Channel options are loaded via a call to the 1oad options routine That routine is part of this example and as discussed later uses the SDK routines for obtaining channel option values from the channel s option file 3 The message dequeue processing loop is initiated with a call to mtaDequeueStart 4 For each queued message to be processed process message will be called by mtaDequeueStart 5 Amessage enqueue is started This enqueue is used to re enqueue the queued message currently being processed As the message is processed its non harmful content will be copied to the new message being enqueued 6 Theenvelope recipient list is copied from the queued message to the new message being enqueued 7 Sincethis is an intermediate channel that is it doesn t effect final delivery of a message successful processing of a recipient address is associated with a disposition of MTA DISP RELAYED 8 After processing the message s envelope mtaDecodeMessage is invoked to decode the message breaking it into individual MIME message parts mtaDecodeMessage is told to use the current dequeue context as the input source for the message to decode This supplies the queued message being processed as input to the MIME decoder Further the current enqueue context is supplied as the o
252. outine 94 decoding caller supplied routines decode inspect 88 decode read 87 decode write 94 decoding messages contexts 94 input sources 87 MIME format 85 output destination 93 simple sample decoding program 89 simple virus scanner sample program 95 decoding routines mtaDecodeMessage 135 mtaDecodeMessagelnfolnt 145 mtaDecodeMessagelnfoParams 147 mtaDecodeMessagelnfoString 149 mtaDecodeMessagePartCopy 151 mtaDecodeMessagePartDelete 152 deferred messages channel configuration 54 definition 54 disposition 52 notifications 53 deferring recipients 54 delivery receipts 199 204 dequeue context 25 26 dequeuing caller supplied routines process_done 62 process_message 54 dequeuing messages aborting 54 162 accessing queued messages 49 basic steps 50 calling order 82 complex dequeuing sample program 63 ending 162 envelope fields 156 intermediate channel sample program 73 Section D process_message 54 calling order dependencies 82 routines 47 cc addresses 202 239 CHANLENGTH 32 defined 27 channel configuration message deferral 54 channels backoff keyword 54 channel definition 39 channel name 26 channel program 21 38 channel programs 21 channel queue defined 21 intermediate 21 log file 38 logging keyword 33 master 21 message queue 21 name determination 31 32 naming conventions 26 slave 21 Communications Services documentation 15 compiling mtaSend programs 242 compiling programs MTA S
253. owed by two additional call arguments 1 The address of a pointer to receive the address of the NULL terminated envelope From address 2 The address of a size t to receive the length of that address A NULL value can be passed for the env from len argument Return the intermediate form of the last envelope recipient address returned by mtaDequeueRecipientNext If that routine has not yet been called for the dequeue context then an MTA NO error code will be returned This item code must be followed by two additional call arguments 1 The address of a pointer to receive the address of the NULL terminated intermediate recipient address 1 The address of a size t to receive the length of that address A NULL value can be passed for the ircpt to len argument Specify a pointer to an item list array The item list array must be terminated with a final array entry with an item code value of zero For further information on item list usage see Item Codes and ltem Lists on page 28 Chapter 6 MTA SDK Reference 9 Additional Arguments const char env from size t env from len const char ircpt to size t ircpt to len mta item list t item list Item Codes Continued MTA ENV FROM MTA IRCPT TO MTA ITEM LIST Return Values Return Values Description 0 Normal successful completion MTA BADARGS Received for one of three reasons 1 A NULL value was supplied for the dg ctx call argum
254. page 69 For the output generated by this code see Output from the Complex Dequeue Example on page 71 Code Example 4 2 A Complex Dequeue Example dequeue complex c Dequeuing with more than one thread used x include stdio h include stdlib h if defined _WIN32 include unistd h endif include string h include lt sys types h gt include lt sys stat h gt include fcntl h include lt errno h gt include mtasdk h See explanatory comment 1 typedef struct int debug Debug flag int max_count Maximum number of messages per BSMTP file my global context t See explanatory comment 2 typedef struct int id Dequeue thread s id FILE fp Dequeue thread s current output file Chapter 4 Dequeuing Messages 3 A Complex Dequeuing Example Code Example 4 2 A Complex Dequeue Example Continued int count Messages output by this dequeue thread my thread context t static const char NotifyToStr int ret type char buf static const char UniqueName char buf size t maxbuf const char suffix static mta dq process done t process done static mta dq process message t process message int main my_global_context_t gctx int ires Initialize the MTA SDK us if ires mtaInit 0 mtaLog mtaInit returned d sWn ires mtaStrError ires 0 return 1 The global context
255. pientDisposition fora discussion of the disposition settings MTA ITEM LIST mta item list t Specify a pointer to an item list array The item list array item list must be terminated with a final array entry with an item code value of zero For further information on item list usage see Item Codes and ltem Lists on page 28 MTA REASON const char reason When deferring processing of a message the reason for the deferral may be saved as part of the messages delivery history This delivery history may be viewed by system managers with the MTA am utility It may also be reported in delay notifications Size t reason len This item code must be followed by two additional call arguments 1 The address of the string containing the reason text 1 The length in bytes of the reason text If a value of zero is passed for the length then the reason text must be NULL terminated 164 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDequeueRecipientDisposition Return Values Return Values Description 0 Normal successful completion MTA BADARGS Received for one of two reasons 1 A NULL value was supplied for the dq ctx call argument an invalid dequeue context was supplied for dq_ctx 2 Arequired argument to an item code was NULL MTA NO Unable to dequeue the message This error can result from an attempt to enqueue a new message to a subset of recipients MTA NOSUCHITEM An invalid item code was specified MT
256. r based upon US ASCII ordinal values When this flag has a value of zero the list of envelope recipient addresses will not be sorted This item code must be followed by one additional argument the address of size t to store the setting s value in MTA CHANNEL char channel Obtain the name of the channel that this message is being enqueued by size t channel len This item code must be followed by two additional call arguments 1 The address of a pointer to receive the address of the NULL terminated channel name 2 The address of a size t to receive the length of the channel name A NULL value may be passed for the channel len argument MTA DELIVERY FLAGS size t dflags Return the envelope delivery flags set for the entire message by mtaEnqueueStart This item code must be followed by one additional call argument the address of a size t to receive the delivery flag setting MTA ENV FROM const char env from Retrieve the envelope From address specified when the enqueue was started with mtaEnqueueStart size t env from len This item code must be followed by two additional call arguments 1 The address of a pointer to receive the address of the NULL terminated envelope From address 2 The address of a size t to receive the length of that address A NULL value may be passed for the env from len argument MTA ENV ID const char env id Obtain the envelope ID specified with mtaEnqueueStart
257. r 114 232 mtaVersionRevision 114 232 option processing mtaOptionFinish 115 218 mtaOptionFloat 115 219 mtaOptionInt 115 220 mtaOptionStart 115 222 mtaOptionString 115 225 slave channels defined 21 Solaris Index 277 Section W 278 Messaging Server 6 2005Q1 MTA Developer s Reference
258. r is the data itself NULL terminated However in the case of binary data there may be carriage returns line feeds or even NULLs embedded within the data itself data len The length in bytes of the data being presented This length may be 0 which indicates a blank line and not the absence of any data MTA DATA NONE Output Routine When an output routine is not used the inspection routine can detect the transition from one message part to another by observing the part number on each call The part number is obtained by calling mt aDecodeMessageInfoString with an item value of MTA DECODE PART NUMBER When the optional output routine pointed to by the output argument is used an additional data type MTA DATA NONE is presented to the inspection routine It is presented to the inspection routine after the part s header and entire content have been presented However no data is actually presented for the DATA NONE type As such this data type merely serves to 1 let the inspection routine know that the entire part has now been presented and 2 allows the inspection routine a final mtaDecodeMessage 138 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDecodeMessage chance to delete the part from the data being output to the output routine For example it allows a virus scanner to be activated and a judgment passed Based upon the result of the virus scan the part can then either be copied to the outp
259. rates optional diagnostic output Calling mtaLog directs the output to the appropriate location stdout if the program is run manually and the channel log file if the program is run by the Job Controller Chapter 4 Dequeuing Messages 69 A Complex Dequeuing Example 9 mtaDequeueStart calls process message once for each queued message to be processed On the first call the memory pointed at by my ctx 2 is guaranteed to be NULL The value of the first call argument passed to mtaDequeueStart is passed to process message as the my ctx 1 call argument 10 The global context contains information pertinent to all the dequeue threads generated by the call mtaDequeueStart 11 process message uses a per thread context to save data across all calls to itself by a single dequeue thread 12 mtaDequeueInfo is used to obtain the envelope ID and RFC 1891 notification flags if any associated with the message being processed 13 mtaDequeueRecipientNext is used to obtain each envelope recipient address one address per call When there are no more recipient addresses to obtain the routine returns the status MTA_EOF 14 Each recipient is marked as delivered with a call to mtaDequeueRecipientDisposition An actual channel program would typically not make this call until after processing the message further 15 Ifprocess message returns without dequeuing the message mtaDequeueStart defers the message for a later del
260. red arguments and gives a description of each Description Specify a domain name to append to short form addresses such as sue in order to create a fully qualified address for example sue siroe com It must be followed by two additional call arguments the domain name to use and the length in bytes of that domain name If a value of 0 is passed for the length then the domain name must be NULL terminated Specify a pointer to an item list array The array must be terminated with a final array entry with an item code value of 0 For further information on item lists see Item Codes and Item Lists on page 28 Item Codes Additional Arguments MTA DOMAIN const char domain size t domain len MTA ITEM LIST mta item list t item list Return Values Return Value Description 0 Normal successful completion TA BADARGS A NULL value was supplied for the address list argument or an optional item code argument TA NO Unable to parse the address list The likely cause is that one or more addresses in the list is syntactically invalid TA NOMEM Insufficient virtual memory TA NOSUCHITEM An invalid item code was supplied TA STRTRUERR Item code string argument is too long Example See the code example for mtaAddressGetN for a sample code fragment that uses mtaAddressParse mtaAddressToChannel Determine which channel an address rewrites to Chapter 6 MTA SDK Reference 123 mtaAddressToChannel
261. red by process_message in the ctx2 call argument for this thread ctx1 The caller supplied private context passed as ctx1 to mtaDequeueStart The following code example demonstrates the type of actions taken by a process_done routine void process done ctx2 ctxl struct our_state_t state struct our_state_t ctx2 if state return Take steps to undo the state for example close any sockets or files Free the memory allocated by process message to store the state xf free state Messaging Server 6 2005Q1 MTA Developer s Reference 62 A Complex Dequeuing Example A Complex Dequeuing Example The program shown in Code Example 4 2 is a more complicated version of the simple example see A Simple Dequeue Example on page 56 In this example more than one concurrent dequeue thread is permitted Additionally better use is made of the context support provided by mtaDequeueStart and a procedure to clean up and dispose of per thread contexts is provided After the Messaging Server product is installed these programs can be found in the following location msg server base examples mtasdk Some lines of code are immediately preceded by a comment of the format See explanatory comment N where N is a number The numbers are links to some corresponding explanatory text in the section that follows this code see Explanatory Text for Numbered Comments on
262. red to as enqueuing a message This choice of terminology reflects the fact that each message submitted to the MTA for delivery is placed into one or more message queues Using its configuration the MTA determines how to route each message to its destination and which message queues to place each the message into However programs enqueuing messages do not need to concern themselves with these details they merely supply the message s list of recipients and the message itself The recipients are specified one by one as RFC 2822 conformant Internet email addresses The message header and content is supplied in the form of an RFC 2822 and MIME conformant email message When starting a coding project to enqueue messages to the MTA always stop to consider whether simply using SMTP will be acceptable The advantage of using SMTP is that it will work with any MTA SMTP server making it portable The disadvantages are poorer performance and lack of flexibility and control This chapter covers the following enqueuing topics Basic Steps to Enqueue Messages on page 42 Originating Messages on page 43 e A Simple Example of Enqueuing a Message on page 43 Transferring Messages into the MTA on page 46 e Intermediate Processing Channels on page 46 Delivery Processing Options Envelope fields on page 47 e Order Dependencies on page 47 41 Basic Steps to Enqueue Messages Basic Steps to Enqueue Messages
263. ress MTAs transporting the message use it as a return path that is the address to which notifications about the message should be returned Specifically it is the address to which the message will be returned in the form of a non delivery notification NDN should the message prove undeliverable It is also the address to which any delivery status notifications DSNs will be sent As such the envelope From address specified should be an address suitable for receiving such notifications NOTE Automatically generated messages such as NDNs and DSNs are required to have an empty envelope From address that is a zero length address These rules are mandated by Internet standards so as to prevent broad classes of looping messages It is imperative that they be observed failure to do so may result in exponentially growing mail loops that affect not only your own mail system but possibly mail systems of other sites with which you exchange mail When explicitly specifying the envelope From address via the env rom and env from len call arguments note the following points The length of the address may not exceed 256 bytes This is the length limit imposed by RFCs 2821 and 2822 It is also the size denoted by the ALFA SIZE constant Older MTAs may not support envelope addresses of lengths exceeding 129 bytes This is the length limit imposed by RFC 821 e To specify an empty envelope From address supply an empty string for env fro
264. ress field must be NULL terminated When the item code has an associated integral value this field supplies that value Not all actions require the use of this field Only used by mt aSend Not used by other MTA SDK routines Fields Continued size titem length int item status const char item smessage Only used by mtaSend Not used by other MTA SDK routines The end of the array is signified by an array entry whose item code field has the value zero MTA END LIST As an example of using MTA ITEM LIST consider the following mtaInit call MTA DEBUG DEQUEUE MTA DEBUG DECODE 0 istat mtaInit MTA DEBUG SDK MTA DEBUG 05 MTA DEBUG MM 4 In the above call the decision to enable the listed debug modes is made at compile time Using an item list array allows the decision to be made at run time as illustrated in the following example item list t item list 6 index x 0 debug_sdk tem_list index item_code MTA_DEBUG_SDK debug_os tem_list indext item_code MTA DEBUG OS debug_mm tem list index item code MTA_DEBUG_MM tem list index item length 4 debug dq tem_list index item_code MTA DEBUG DEQUEUE debug decode tem list indext item code MTA DEBUG DECODE t mtalInit MTA ITEM CODE item list 0 Chapter 1 MTA SDK Concepts and Overview 9 ta int 3 inde E H H i 1 i i if 1 LEN i i
265. rl Skip over the ptr2 fext 102 Messaging Server 6 2005001 MTA Developer s Reference A Simple Virus Scanner Example Code Example 5 2 Decoding MIME Messages Complex Example Continued ptr2 char 0x01 len len ptrl buf for i 0 1 gt len i ptr2 tolower ptrl ptr2 char 0x0 ptr2t 0 Now return 1 if the string occurs in options bad file types return strstr options gt bad_file types fext 1 0 10806 options Load our channel options from the channel s x option file See explanatory comment 15 ui static int load options our options t options char buf BIGALFA_SIZE 1 size_t buflen i mta_opt_t channel_opts int ires const char ptr0 char ptrl Initialize the our private channel option structure f memset options 0 sizeof our options t Access the channel s option file See explanatory comment 16 channel 0065 NULL if ires mtaOptionStart amp channel opts NULL 0 0 mtaLog Unable to access our channel option file return ires DEBUG 0 1 f options gt debug 0 mtaOptionInt channel opts DEBUG 0 amp options debug if options gt debug mtaDebug MTA_DEBUG_SDK 0 BAD MIME TYPES typel subtypel type2 subtype2 d Chapter 5 Decoding Messages 3 lt 0x01 gt typel subtypel lt 0x01 gt type2 subtype2
266. rminated A NULL may be passed for this call argument if you do not wish to receive the pointer address len The length in bytes of the selected address not including any NULL terminator NULL may be passed for this call argument if you do not wish to receive the length elements A bitmask indicating which RFC 822 mailbox elements of the address to return such as phrase route local part or domain Any combination of these elements may be returned Description This routine retrieves the Nth address from a list of parsed addresses The list of addresses must first be parsed with mtaAddressParse Either the entire address or just a portion of it may be retrieved Elements Argument Using the nomenclature of RFC 822 an address has the following four element format phrase lt route local part domain gt NOTE The route element is referred to as a source route and is rarely seen An example address with all four elements is Judy Smith lt siroe com judy smith email siroe com gt Chapter6 MTA SDK Reference 119 The elements argument is a bitmask indicating which of these elements to return The bitmask is formed by a logical OR of the following symbolic constants defined in the mtasdk h header file e MTA ADDR PHRASE In the example the phrase part is Judy Smith e MTA ADDR ROUTE In the example the route part is siroe com e MTA ADDR LOCAL In the example the local part is judy s
267. rned no longer exists That is dequeuing a message relieves the MTA of all further responsibility for the message the responsibility is assumed to have been passed on to some other entity such as another MTA or a message store Chapter 1 MTA SDK Concepts and Overview 25 The channel name used by the program identifies the MTA message queue being serviced by the program The channel name can either be explicitly specified by the program or determined from the run time environment using the PMDF CHANNEL environment variable NOTE Channel naming conventions the name must be 32 bytes or less should be in lower case and if the channel will have multiple instantiations then it should be given a generic name such as tcp and then each instantiation can be given a specific version of it such as tcp local tcp auth tcp intranet Multiple programs may simultaneously process the same message queue The SDK and Job Controller will automatically coordinate such efforts using file locks to prevent two or more programs or threads from simultaneously processing the same message When the message processing program see Dequeue Message Processing Routine Tasks on page 52 is called the message to be processed is locked so that no other jobs may access that message The message is then unlocked when mtaDequeueMessageFinish is called or when the program exits normally or abnormally Threads and Dequeue Contexts Each individual message being d
268. rogramming Considerations For an example of how to enqueue a message see Code Example 3 1 on page 44 Messaging Server 6 2005Q1 MTA Developer s Reference 22 Enqueuing Messages Message Components This section describes the three message components envelope header and body Envelope The message envelope contains the envelope From address and the list of envelope To addresses The envelope is created by the SDK as the message is enqueued The addresses to be placed in the envelope must conform to RFC 2822 The envelope To addresses are often referred to as envelope recipient addresses Programs should rely solely upon the MTA SDK routines to read and write envelope information since the queued message file formats are subject to change Using the SDK routines insulates programmers from format changes The routines mtaEnqueueStart and mtaEnqueueTo are used to construct a message envelope Header The message header contains RFC 2822 style header lines The program enqueuing the message has nearly complete control over the contents of the header and can specify as many or as few header lines as it sees fit with a few exceptions A header must have at a minimum three lines From Date and at least one recipient header line such as To Cc or Bcc As the message is enqueued the SDK will do its best to supply any mandatory header lines that are missing as well as take some measures to ensure that the content
269. routines mtaDone 183 mtalnit 212 input routine decode read 87 inspection routine decode inspect 88 intermediate channels defined 21 re enqueuing 71 sample enqueuing and dequeuing program 73 item codes 28 item list defined 28 J Job Controller 26 K keywords backoff 54 logging 33 274 Messaging Server 6 2005Q1 MTA Developer s Reference Section 0 mtaEnqueuelnfo 113 189 mtaEnqueueStart 113 193 mtaEnqueueTo 113 200 mtaEnqueueWrite 113 206 mtaEnqueueWriteLine 113 209 mtaErrno 113 211 mtalnit 113 211 212 mtaLog 114 215 mtaLog vs MTA log file 39 mtaLogv 114 217 mtaOptionFinish 115 218 mtaOptionFloat 115 219 mtaOptionInt 115 220 mtaOptionStart 115 222 mtaOptionString 115 225 mtaPostmasterAddress 114 227 mtaSend access privileges 241 basic steps for sending a message 237 compiling and linking programs 242 envelope addresses 238 header from addresses 238 message content body 240 message header 240 sample programs input procedure generates message body 247 sending a message to multiple recipients 245 sending a simple message 243 specifying an initial message header 244 to cc and bcc addresses 239 mtaStackSize 114 229 mtaStrError 113 230 mtaUniqueString 114 230 mtaVersionMajor 114 231 mtaVersionMinor 114 232 mtaVersionRevision 114 232 0 option processing finishing 218 floating point values 219 Index 5 mtaAccountingLogClose 117 mtaAddressToChannel 123 mtaBlockSize 1
270. rray The item list array must be item list terminated with a final array entry with an item code value of zero For further information on item list usage see Item Codes and Item Lists on page 28 MTA REASON const char errmsg Provide the address of a string pointer to receive any extended error message information In the event of an error associated with submitting the message to the MTA then the MTA may return additional information By providing this pointer that additional information may be obtained for diagnostic purposes size t errmsg len This item code should be followed by two additional item codes 1 The address of a pointer to receive the address of the NULL terminated error text 2 The address of a size t to receive the length of that error text A value of NULL may be passed for the errmsg_len argument 188 Messaging Server 6 2005Q1 MTA Developer s Reference mtaEnqueuelnfo Return Values Return Values Description 0 Normal successful completion BADARGS This value is returned for one of the following reasons 1 A NULL value was supplied for the ng ctx call argument 2 An invalid enqueue context was supplied for ctx 3 Arequired argument to an item code was NULL TA FCREATE Insufficient disk space or other I O error encountered while attempting to create or close a message file or a temporary file TA FIO An I O error occurred while writing message files to the MTA cha
271. rther information imsimta test rewrite Messaging Server 6 2005Q1 MTA Developer s Reference 130 mtaDateTime Error Status Codes Description MTA NO One of the following errors occurred 1 Unable to determine the channel name from the runtime environment 2 Unable to initialize the MTA SDK For further information issue the following command imsimta test rewrite MTA NOSUCHCHAN The selected channel name does not appear in the MTA configuration file imta cnf MTA NOSUCHITEM An invalid item code was specified Example printf Host name 5 mtaChannelToHost NULL NULL MTA CHANNEL tcp local 0 0 mtaDateTime Obtain the current date and time in an RFC 822 and RFC 1123 complaint format Chapter 6 MTA SDK Reference 1 Syntax const char mtaDateTime char date size t date len size t date len max time t time Arguments Arguments Description date A pointer to a buffer to receive the NULL terminated date and time string To avoid possible truncation of the string this buffer should be at least 81 bytes long date len An optional pointer to a size t to receive the length in bytes of the returned date and time string This length does not include the NULL terminator that terminates the host name A value of NULL can be passed for this call argument date len max The maximum size in bytes of the buffer pointed at by the date argument time The date and t
272. s MTA MODE TEXT Chapter8 mtaSend Routine Specification 261 The item address and item length fields are ignored for this item code MTA MODE TEXT Read subsequent input files as record oriented text files This setting may be changed with the MTA MODE BINARY item code The default access mode is MTA MODE TEXT The item address and item length fields are ignored for this item code MTA MSG FILE Specify an input file to read and include in the message body The file will be read using the current access mode and encoded using the current encoding as specified by MTA MODE and MTA ENC item codes The item address and item length fields specify the address and length of a text string containing the name of the input file The length of the string may not exceed ALFA SIZE bytes MTA MSG PROC Specify the address of a procedure that will return one line at a time data for the message body Each line of input obtained from the procedure will be treated using the current access mode and encoded using the current encoding as specified by MTA MODE and MTA ENC item codes Note however that the block access mode will not be applied to input procedures The item address field specifies the address of the procedure to invoke The item length field is ignored The calling format that must be used by the procedure is given in Message Headers and Content on page 240 MTA NOBLANK When processing multiple input source
273. s and may be subject to the export or import laws in other countries Nuclear missile chemical biological weapons or nuclear maritime end uses or end users whether direct or indirect are strictly prohibited Export or reexport to countries subject to U S embargo or to entities identified on U S export exclusion lists including but not limited to the denied persons and specially designated nationals lists is strictly prohibited DOCUMENTATION IS PROVIDED AS IS AND ALL EXPRESS OR IMPLIED CONDITIONS REPRESENTATIONS AND WARRANTIES INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE OR NON INFRINGEMENT ARE DISCLAIMED EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID Copyright 2005 Sun Microsystems Inc 4150 Network Circle Santa Clara California 95054 Etats Unis Tous droits r serv s Sun Microsystems Inc d tient les droits de propri t intellectuels relatifs la technologie incorpor e dans le produit qui est d crit dans ce document En particulier et ce sans limitation ces droits de propri t intellectuelle peuvent inclure un ou plusieurs des brevets am ricains list s l adresse http www sun com patents et un ou des brevets suppl mentaires ou des applications de brevet en attente aux Etats Unis et dans les autres pays CE PRODUIT CONTIENT DES INFORMATIONS CONFIDENTIELLES ET DES SECRETS COMMERCIAUX DE SUN MICROSYSTEMS INC SON UTILISATION SA DIVULGAT
274. s created by mtabequeueStart each sequentially process multiple messages That is mtaDequeueStart does not create a distinct thread for each and every queued message to be processed For a list of the tasks the processing routine should do see Caller Supplied Processing Routine on page 51 NOTE The mtaDequeueStart routine will use one or more threads with each thread calling the message processing routine The maximum number of threads allowed can be set when calling mtaDequeueStart Consequently a program that does not support threading should specify a maximum of one thread when it calls mtaDequeueStart For a list of the tasks the processing routine should do see Dequeue Message Processing Routine Tasks 4 After mtaDequeueStart returns deallocate SDK resources and data structures with a call to mtaDone Caller Supplied Processing Routine Channel programs typically perform some form of processing on each message they dequeue For instance virus scanning MMS conversion decryption delivery to a proprietary messaging system and so forth When using the MTA SDK channel programs must provide a routine which initiates this processing on a per message basis That is programs must supply a routine that to be called to process a single queued message Throughout the rest of this text this caller supplied routine will be referred to as the caller supplied processing routine or for short the processing
275. s for To Cc and Bcc addresses This is the default setting The item address and item length fields are ignored for this item code MTA ADR STATUS Return textual status messages for each envelope recipient address that is an active transport address specified with any of these item codes MTA TO MTA CC MTA BCC MTA HDR TO MTA HDR CC Or MTA HDR BCC When a recipient address is successfully processed the value of the associated item status field will be zero and item smessage will be a pointer to a NULL terminated string containing the rewritten form of the address When a recipient address fails to be processed successfully the value of the associated item status field will be non zero and item smessage will be a pointer to a NULL terminated error message string After calling mtaSend with MTA ADR STATUS call the mtaSendDispose function to dispose of any dynamic memory allocated by mtasena The item address and item length fields are ignored for this item code MTA BCC Specify a blind carbon copy Bcc address The item address and item length fields specify the address and length of a string containing a Bcc address The length of the address may not exceed ALFA SIZE bytes MTA BCC is used to specify a Bcc address that should appear in both the message s header and envelope MTA BLANK When processing multiple input sources insert a blank line between the input from each source Ordinarily the input files
276. s of the header lines conform to any relevant standards If the From header line is omitted by the program using the SDK the SDK code will construct a default header line from the envelope From address This may not always be appropriate for instance when mail is addressed to a mailing list that specifies an Errors to address then the Errors to address should be used as the envelope From address In this case it is not appropriate to derive the header From line from the envelope From address If the Date header line is omitted the SDK code will supply it as well as a Date warning header line Finally if no recipient header lines are present then the SDK code will generate them using the envelope recipient addresses Any addresses appearing in the message header should conform to RFC 2822 The header is written line by line using the routines mtaEnqueueWrite and mtaEnqueueWriteLine Chapter 1 MTA SDK Concepts and Overview 23 Body The optional message body contains the content of the message As with the message header the program enqueuing the message has nearly complete control over the contents of the message body The only exception to this is when the message is structured with multiple parts or requires encoding for example if it contains binary data or lines requiring wrapping In such cases the SDK will ensure that the message body conforms to MIME standards RFCs 2045 2049 As with the message header m
277. sage presents each atomic message part to the inspection routine one line at a time The presentation begins with the part s header lines Once all of the header lines have been presented the lines of content are presented So that the inspection routine can tell if it is being presented with a line from the header or content of the message a data type indicator is supplied to the inspection routine each time it is called In regards to lines of the message s content the data type indicator discriminates between text and binary content Text content is considered any content with a MIME content type of text or message for example text plain text html message rfc822 while binary content is all other MIME content types application image and audio When writing an inspection routine for use with mt abecodeMessage the following points apply Message parts need not have any content A common case is a single part message with no content for which the sender used the Subject header line to express their communique Inthe case of a non multipart message the message has a single part The header for this sole part is the header for the message itself As noted previously there may or may not be any content to this single part Messaging Server 6 2005Q1 MTA Developer s Reference 88 A Simple Decoding Example Inthe case of a multipart message individual parts need not have a part header In such cases MIME s def
278. sfer encoding base64 2H Content disposition attachment filename a ps 2B 8 100 100 moveto 300 300 lineto stroke showpage The Output Destination When an optional output destination is supplied to mtaDecodeMessage the processed input message is subsequently written to the output destination When conversion to MIME is requested the output message will be the result of the conversion Additionally the written message will reflect any changes made by the inspection routine with mtaDecodeMessagePartDelete That routine may be used to delete an atomic part or replace the part with new caller supplied content The output destination can be either a message submission to the MTA that is an ongoing enqueue or an arbitrary destination represented by a caller supplied output routine Enqueue Context When using a message enqueue context you must do the following 1 Supply the enqueue context along with the MTA_DECODE_NQ item code 2 Specification of the message s recipient list must have already been completed with mtaEnqueueTo before calling mtaDecodeMessage 3 mtaEnqueueFinish must not yet have been called for the enqueue context Chapter 5 Decoding Messages 3 After the call to ntabecodeMessage has completed successfully complete the message enqueue with ntaEnqueueFinish In the event of an error the message submission should be cancelled with mt aEnqueueFinish mtaDecodeMessage wri
279. specified option The MTA allows channel options to have a maximum length of BIGALFA SIZE bytes As a result this buffer should in general have a length of at least BIGALFA_SIZE 1 bytes If the option was not specified in the option file then the contents of the buffer is left untouched An optional pointer to a size t to receive the length in bytes of the returned option value string str A value of NULL may be passed for this call argument The maximum size in bytes of the buffer pointed at by str Arguments Arguments opt ctx name len str str len str len max Description Use mtaOptionString to retrieve the string representation of an option s value If the option is specified in the option file then its value and length will be returned via the str and str len call arguments If the option is not specified then no value is returned and the memory pointed at by str and str 1en are left unchanged This routine can be called with a NULL value for the opt ctx argument When this is done mtaOptionString immediately returns with a status code of zero and no option value is returned mtaOptionString 226 Messaging Server 6 2005Q1 MTA Developer s Reference mtaPostmasterAddress Return Values Return Values Description 0 Normal successful completion MTA STRTRU Supplied buffer pointed at by buf is too small The returned value has been truncated to fit Truncated value is NULL terminate
280. sposition argument Delivery Status Dispositions Description MTA DISP DEFERRED Processing for this recipient has experienced a temporary failure for example the network is temporarily down the disk is currently full the recipient is presently over quota Schedule a later processing attempt for this recipient 166 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDequeueRecipientDisposition Description Final delivery has been effected for this recipient address Any required delivery notifications should be generated Intermediate processing channels should use DISP RELAYED rather than DISP DELIVERED Use of MTA DISP DELIVERED by an intermediate processing channel might incorrectly generate a delivery status notification when final delivery has not yet been effected Processing for this recipient has experienced a permanent failure The message is and will remain undeliverable for this recipient No further delivery attempts are to be made for this recipient Any required non delivery notifications should be generated The message has been successfully processed for this recipient No further processing by this channel is needed for this recipient address No delivery status notification is generated as final delivery will be effected by another entity capable of generating any needed notification messages This disposition should be used by intermediate processing channels It shou
281. ssing threads to exit Return to the caller of mtaDequeueStart mtaDequeueThreadld mtaDequeueThreadId Return the thread ID associated with the specified dequeue context Syntax int mtaDequeueThreadId mta dq t dq ctx Arguments Arguments Description dq ctx A dequeue context created by mtaDequeueStart Description Each processing thread is assigned a unique integer identifier referred to as a thread ID This thread ID is intended as a diagnostic aid when debugging channel programs Showing it with diagnostic messages helps to differentiate the work of one thread from another in the channel s debug log file The thread ID can also be obtained with mtaDequeueInfo 182 Messaging Server 6 2005Q1 MTA Developer s Reference mtaDone Return Values In the event of an error the value 1 is returned and mta errno is set to indicate the error status code Error Status Code Description MTA BADARGS A NULL value was supplied for the dq ctx call argument or an invalid dequeue context was supplied for dq_ctx Example mtaLog 08d process message called with dq ctx p mtaDequeueThreadId dq ctx dq ctx mtaDone Release resources used by the MTA SDK Syntax void mtaDone void Arguments None Description Once use of the MTA SDK has been finished mt aDone should be called to release any resources used by the MTA SDK The routine should be called while the calling process is si
282. t dctx MTA PART NUMBER mtaDecodeMessageInfoParams Obtain an option context describing the current message part s content parameters Syntax mta opt t mtaDecodeMessageInfoParams mta decode t dctx int item mta opt t params Arguments Arguments Description dctx A decode context created by mt aMessageDecode item Item identifier specifying which content parameter list to return See the description that follows for the list of permitted values for this argument params An optional pointer to receive the address of the option context describing the requested parameter list Description This routine returns the parameter lists for either the Content type or Content disposition header lines When mtaDecodeMessage calls either a user supplied inspection or output routine it provides a decode context describing the current part being processed The following table lists the values for the item argument and gives a description of each Values Description MTA DECODE CDISP PARAMS Parameters associated with the Content disposition header line if any MTA DECODE CTYPE PARAMS Parameters associated with the Content type header line if any Chapter 6 MTA SDK Reference 7 mtaDecodeMessagelnfoParams The option context returned upon normal completion does not need to be disposed of with mtaOptionFinish It will automatically be disposed of by mtaDecodeMessage The values of indiv
283. t aDequeueThreadId Return the thread ID associated with the specified dequeue context 112 Messaging Server 6 2005Q1 MTA Developer s Reference Summary of SDK Routines Description Copy a message from a dequeue context Complete or cancel a message submission Obtain information about a message submission Begin a message submission Add recipients to a message Output a line to the message header or body Output a line to the message header or body Enqueue Enqueue routines are used for enqueuing messages Routine Name mtaEnqueueCopyMessage mtaEnqueueFinish taEnqueueInfo taEnqueueStart mtaEnqueueTo taEnqueueWrite taEnqueueWriteLine Handling 3 3 3 s Error Error handling routines used for error status retrieval Description Obtain the value of the last error status for this thread Map an error status code to a printable string Routine Name mtaErrno mtaStrError Initialization These routines are used for initialization Description Release resources used by the MTA SDK Initialize the MTA SDK Chapter6 MTA SDK Reference 3 Routine Name mtaDone mtaInit Summary of SDK Routines Logging and Diagnostics Logging and diagnostics routines are used to write diagnostic messages to debug log files Routine Name Description mtaDebug Write internal diagnostic information to the debug log file mtaLog Write to t
284. t address The message is sent to one To address a Cc address and a Bcc address After mtaSend is called any status message associated with each address is displayed Chapter7 Using Callable Send mtaSend 245 Examples of Using mtaSend The log output produced by running the program is shown in Example 3 Output The following items of note are identified in the comments in the program Instruct mtaSend to return a status message for each envelope recipient address e Specify some To Cc and Bcc addresses e Send the message Display any returned status messages Code Example 7 3 Sending a Message to Multiple Recipients send multi c Send a message to multiple recipients include lt stdio h gt include lt string h gt include mtasdk h define ITEM item adr item list index item code item item list index item address adr item list index item length adr strlen adr 0 item list index item status 0 item_list index item_smessage NULL main int index 0 istat i mta_item_list_t item_list 7 Specify the Subject header line and message input source ITEM MTA_SUBJECT send multi c ITEM MTA MSG FILE __FILE_ Return per address status error messages ITEM MTA ADR STATUS 0 Instructs mtaSend to return a status message for each envelope recipient address Specify regular Bcc To and Cc addresses ITEM MTA BCC
285. t block waiting on these processes it returns as soon as all requisite copies of the enqueued message have been safely written to disk The subsequent handling of the newly enqueued message is performed by other MTA processes and the program which enqueued the message isn t left waiting for them A message submission can be aborted at any point in Step 2 by calling either mtaEnqueueFinish with the MTA ABORT option specified or mtaDone Using the first method mtaEnqueueFinish aborts only the specified message enqueue context while allowing additional messages to be enqueued Whereas mt aDone Messaging Server 6 2005Q1 MTA Developer s Reference 42 Originating Messages aborts all active message enqueue contexts in all threads and deallocates SDK resources disallowing any further submission attempts until the SDK is again initialized Originating Messages Messages enqueued to the MTA fall into one of two broad classes new messages being originated and messages which were originated elsewhere and which are being transferred into the MTA The former are typically the product of a local user agent or utility which uses the MTA SDK The latter are generated by remote user agents and received by local programs such as SMTP or HTIP servers which then enqueue them to the MTA for routing or delivery or both In either case it is the job of the MTA to route the message to its destination be it a local message store or a remote M
286. t mtaVersionRevision void Arguments None Description Return the revision level associated with the MTA SDK library Return Values The SDK revision level Example printf MTA SDK Version d d d n mtaVersionMajor mtaVersionMinor mtaVersionRevision Chapter 6 MTA SDK Reference 3 mtaVersionRevision 234 Messaging Server 6 2005Q1 MTA Developer s Reference Part Il Callable Send Chapter 7 Using Callable Send mtaSend Chapter 8 mtaSend Routine Specification Chapter 7 Using Callable Send mtaSend The Sun Java System Messaging Server MTA Callable Send facility mtasend is a single procedure that is used to send enqueue mail messages of local origin that is to originate mail from the local host Because the mtaSend routine is not as flexible as the SDK routines and will take possibly undesirable but necessary authentication steps such as the addition of a Sender header line the MTA SDK routines should generally be used by programs that need to resend forward send through a gateway or otherwise route mail messages The mtaSend routine may be used simultaneously with the MTA SDK routines This chapter covers the following topics e Sending a Message Envelope and Header From Addresses e To Cc and Bcc Addresses Message Headers and Content e Required Privileges e mtaSendDispose e Compiling and Linking Programs Examples of Using mtaSend Send
287. t shows how to terminate the header by writing a blank line mtaEnqueueWriteLine nq 0 NULL The following code fragment that produces a Date header line char buf 64 mtaEnqueueWriteLine nq Date 0 mtaDateTime buf NULL sizeof buf 0 0 NULL mtaErrno Obtain the last returned error status for the calling thread Syntax int mtaErrno void Arguments None Description When an MTA SDK routine is called by a processing thread and returns an error status code the SDK saves that status code in thread specific data The same processing thread can obtain the most recently saved status code for its own thread of execution by calling ntaErrno For convenience purposes the ntasdk h header file also defines mta_errno as a macro that calls mtaErrno Specifically Chapter 6 MTA SDK Reference 211 define mta errno mtaErrno Return Values The last error return status code returned by an MTA SDK routine called by this processing thread For a description of the MTA SDK error status codes see Appendix A Error Status Codes Summary on page 265 Example The following code fragment demonstrates how to obtain the most recent error status code for its own thread if TmtaEnqueueStart amp nq from adr 0 0 printf Error returned d n mtaErrno Initialize the MTA SDK Syntax int mtaInit int item code Arguments Arguments Description item co
288. taDequeueStart Message Processing oooooooooo Messaging Server 6 2005Q1 MTA Developer s Reference Processing Procedure cos cccc cio e Er a Ra xe RE ad mde EGG 177 process message SOUBIE AAA A e t e it eoe 178 process done Routine ico e ee ete wiser P ERU IA deeper teed RIT 180 Thread Creation LOOP cuceue te f e hr UR Ix IR eere ER ER E ee ode ds EXPE DEDE 181 mirabequeuelhreadld 22426 eim A rac s Hp A EE Riu S 182 MADONE ia A ot Hen ye seed age Ui Roa ug eden eck Oe Dg Bia dones 183 intabnqueuel opy Message iccoclesssse o a ia da debe ewe be teeta bea get fads 183 ttal nqueue uet cius Eger SR pe be beds 185 intaEnqueuebinish lt i cee d eec ke reve Fre s REP AY da TA rae ru PADO edd ales s 187 mtaEnqueuelnfo i oissiccse r9 Re de err ERES 189 intabnqueueStatt celeres peek us Sead Pe biceneerberierurved 9a eer IE duet UE eee 193 A iii ad tan td 7 200 WINE 2 0 28 see A eet ad ee Glas eee a el Ae Ae Seed gies 206 occi essent mee eam da alee ee Ups 209 Gee eS Padded Lee ASRS SE wie edd EP qEPEPSeUOPe ded epe 211 rl es A A bee A dd 212 PUT AAA A A pee E piss 215 nro T 217 csse cese a awit phew Seca PTT PIT ERR Ee dure Ore ds 218 mtaCpt brnEloat recen lk eb Sn oe Ree AA Ee ee Bae cus 219 MtBOPHOMINE ive PP y as tr IER Y CBS Rad AE A Dr eere dead a ndiae ss 220 intaOptbonStatt iocicseseieco c ee C
289. tem list index item code MTA END LIST ista Item Codes and Item Lists Note that the list of item code arguments must still be terminated with a call argument with value zero Further note that item codes may simultaneously be passed as distinct call arguments and also in item list arrays For example mtaInit MTA DEBUG SDK MTA ITEM LIST item list l MTA INTERACTIVE MTA ITEM LIST item list2 0 In the above the item codes MTA_DEBUG_SDK ITEM LIST MTA INTERACTIVE and MTA ITEM LIST are all explicitly passed as call arguments Additional item codes are passed via the item list arrays item list1 and item list2 When processing item codes they are processed from left to right as the call argument list is interpreted Using the above example mtaInit processes MTA DEBUG SDK then MTA ITEM LIST MTA INTERACTIVE MTA ITEM LIST and finally the terminating 0 call argument which terminates the item code processing When processing the first occurrence of MTA ITEM LIST the entries of item 11561 6 processed starting with the first entry index 0 then the second and so on until an entry with an item code value of 0 is encountered The same processing occurs for item list2 If two item codes set the same underlying option or value the last processed instance of that item code will prevail For example the call mtalnit MTA DEBUG ENQUEUE MTA DEBUG MM 10 0 wi
290. temporary processing error has occurred A number of conditions may generate this error including connectivity problems to LDAP servers virus scanners spam scanners as well as quota problems When the error is the result of an attempt to add an envelope recipient address or to complete a message enqueue additional information may be obtained by either enabling SDK diagnostics with mt aDebug or using the MTA_REASON item code of mtaEnqueueTo or mtaEnqueueFinish In the case of mtaEnqueueTo mtaEnqueueError may also be used to obtain the extended information returned with the MTA REASON item code 3 Bad call arguments supplied to the called routine Typically this will be the result of passing an invalid context or a NULL value for a required parameter 4 End of data reached When returned by mtaDequeueLineNext or mtaDequeueRecipientNext this value does not indicate an error but rather that there are respectively no more message lines or recipients to return 265 Return Code MTA OK MTA ACCESS MTA AGAIN MTA BADARGS MTA EOF Description Unable to create a disk file Typically this will be the result of insufficient disk space insufficient access rights to the channel queue directories or a file system error of some sort The MTA SDK creates both temporary files and message files in the channel queue directories The temporary files result when a message being submitted exceeds in size the
291. tes the entire message header and content There is no need for the caller to write anything to the message s header or content Caller Supplied Output Routine To use a caller supplied output routine for example decode write supply the address of the output routine along with the MTA DECODE PROC item code to mtaDecodeMessage Each line passed to the output routine represents a complete line of the message to beoutput The output routine must add to the line any line terminators required by the output destination for example carriage return line feed pairs if transmitting over the SMTP protocol line feed terminators if writing to a UNIX text file and so forth Decode Contexts Decode Contexts When mtaDecodeMessage calls either a caller supplied inspection or output routine it passes a decode context to those routines Through SDK routine calls this decode context can be queried to obtain information about the message part currently being processed as shown in the following table Description TA DECODE CCHARSET The character set specified with the CHARSET parameter of the part s Content type header line If the part lacks a CHARSET specification then the value us ascii will be returned Obtain with mt aDecodeMessageInfoString TA DECODE CDISP Value of the Content disposition header line less any optional parameters Will be a zero length string if the part lacks a Content disposition header line Obt
292. that of the current process To be considered a privileged process on UNIX systems the process must have the same real user ID UID as either the root or Messaging Server account and Bcc Addresses The list of To Cc and Bcc addresses to send a message to is built up one address at a time with item list entries Each item list entry specifies the type of address To Cc or Bcc and a string containing the address The type of address is denoted by the item code MTA TO MTA CC or MTA BCC associated with the item list entry The mtasend routine uses this information to build the message envelope To address list and To Cc and Bcc header To specify an envelope only address that should not appear in the message header for example an active transport address use MTA ENV TO Likewise to specify a header only address that should not appear in the envelope such as an inactive address use MTA HDR TO MTA HDR CC or MTA_HDR_BCC as appropriate When one or more of the To Cc or Bcc addresses is illegal the mtasend routine will not by default indicate which addresses were in error However the differentiation can be achieved by using the MTA ADR STATUS item code When this item code is used the item status field associated with an address will be set either to zero 0 if the address was accepted or to a non zero value if there was an error processing the address When item status is zero item
293. tification flags Original recipient address This field is specified on a per recipient basis It is used to indicate the original form of the associated recipient s address This original address can then be used in any notification messages Its use allows the recipient of the notification to see the original address they specified rather than its evolved form For example the recipient would see the name of the mailing list they posted to rather than the failed address of some member of the list Set on a per message basis this is an RFC 1891 envelope ID and can appear in RFC 1892 1894 conformant notifications about the message Set on a per message basis this controls if and when the message is fragmented into smaller messages using the MIME message partial mechanism For additional information see the descriptions of mtaEnqueueStart and mtaEnqueueTo Envelope ID Fragmentation size Order Dependencies When you are constructing programs there is a calling order for the MTA SDK routines that must be observed for a given enqueue context some routines must be called before others Figure 3 1 visually depicts the calling order dependency of the message enqueue routines To the right of each routine name appears a horizontal line segment possibly broken across a column for example mtaEnqueueWrite Routines for which two horizontal line segments one atop the other appear are required routines that is routines that
294. til an CFILENAME NONE action is seen in the same item list MTA FILENAME NONE is the default MTA CFILENAME NONE The default action for including or not including the name of the message input file as a parameter in the MIME Content type header line This item code specifies that no input file is to be included When MTA CFILENAME has been specified it will hold for all subsequent input files until an MTA CFILENAME NONE action is seen in the same item list The item address and item length fields are ignored for this item code MTA CTYPE Specify the body of a Content type header line The item address and item length fields specify the address and length of a text string to place in the body of a Content type header line The length of the string may not exceed ALFA SIZE bytes Only one Content type body may be specified Item Codes 254 Messaging Server 6 2005Q1 MTA Developer s Reference Item Codes MTA ENC BASE64 Encode data from all subsequent input sources using MIME s BASE64 encoding This setting may be changed with any of the other MTA ENC item codes The default encoding is MTA ENC UNKNOWN The item address and item length fields are ignored for this item code MTA ENC BASES85 Encode data from all subsequent input sources using Adobe s ASCII85 encoding BASE85 This setting may be changed with any of the other MTA_ENC_ item codes The default encoding is ENC UNKNOWN The item addr
295. tion value is returned name Name of the option to obtain the value for The length of this string should not exceed ALFA SIZE bytes This string must be NULL terminated if a value of zero is passed for len len Length in bytes not including any NULL terminator of the option name supplied with name If a value of zero is supplied then the option name string must be NULL terminated val Pointer to a floating point of type double to receive the option s value If the option was not specified in the option file then the value referenced by this pointer will be left unchanged Description Use mtaOptionFloat to retrieve the value of an option interpreting its value as a floating point number If the option is specified in the option file and its value is a valid floating point number then its value will be returned using the val call argument If the option is not specified or its value does not correctly specify a floating point number then no value is returned and the memory pointed at by val is left unchanged The mtaOptionFloat routine can be called with a NULL value for the opt ctx argument When this is done mtaoptionFloat immediately returns with a status code of zero and no value is returned This routine does not provide an indication of whether or not the option was specified in the option file If it is important to know whether or not the option was specified then use mtaOptionString to test to see if the option w
296. tput from low level message enqueue routines Can be used to diagnose the address rewriting process destination channel selection header processing and other types of processing that occurs when a message is enqueued Enabling this diagnostic output is the equivalent of setting MM DEBUG 5 in the option dat file Enable diagnostic output from the low level message enqueue routines The item code must be followed by one additional call argument the debug level to use The value of level ranges from 0 to 20 Enqueue diagnostics can be used to diagnose the address rewriting process destination channel selection header processing and other types of processing that occurs when a message is enqueued Enabling this diagnostic output is equivalent to setting DEQUEUE DEBUG level in the option dat file Enable diagnostic output from the low level operating system dependent routines This output is helpful when diagnosing problems associated with creating opening writing or reading files This typically happens when attempting to enqueue messages which requires permissions to create and write messages in the MTA queues Enabling this output is equivalent to setting 05 DEBUG 1 in the option dat file Enable diagnostic output for the MTA SDK When this is enabled diagnostic information will be output whenever the SDK returns an error result Specify a pointer to an item list array The item list array must be terminated with a
297. tput the line See explanatory comment 17 fprintf tctx gt fp s n len line If ires MTA EOF then we exited the loop normally If ires MTA EOF then we exited the loop normally otherwise there s been an error of some sort ui if ires MTA_EOF return ires Output the command to terminate this message fprintf tctx gt fp n And dequeue the message See explanatory comment 18 ires mtaDequeueMessageFinish dq 0 All done might as well return ires as our result return ires Convert a bitmask of MTA NOTIFY flags to a readable string xf See explanatory comment 19 static const char NotifyToStr int ret type char buf if buf Doing a RET parameter to a MAIL FROM command return ret type amp MTA NOTIFY CONTENT FULL FULL HDRS buf 0 0 if ret type 6 MTA NOTIFY SUCCESS strcat buf SUCCESS if ret type amp MTA NOTIFY FAILURE if buf 0 strcat buf strcat buf FAILURE if ret type 6 MTA NOTIFY DELAY if buf 0 562085 buf strcat buf DELAY if buf 0 68 Messaging Server 6 2005001 MTA Developer s Reference A Complex Dequeuing Example Code Example 4 2 A Complex Dequeue Example Continued strcat buf NEVER return buf Generate a unique string suitable for use as a file name See explanatory comment 20 static const
298. ually depicts the calling order dependency of the message dequeue routines To the right of each routine name appears a horizontal line segment possibly broken across a column for example mt aDequeueRecipientNext Routines for which two horizontal line segments one atop the other appear are required routines that is routines that must be called in order to successfully enqueue a message The required routines are mtaInit mtaDequeueStart mtaDequeueRecipientNext and mtaDqueueMessageFinish To determine at which point a routine may be called start in the leftmost column and work towards the rightmost column Any routine whose line segment lies in the first leftmost column may be called first Any routine whose line segment falls in the second column may next be called after which any routine whose line segment falls in the third column may be called and so forth When more than one routine appears in the same column any or all of those routines may be called in any order Progression from left to right across the columns is mandated by the need to call the required routines After calling mtaDequeueRewind the read point into the underlying queued message file is reset to the start of the message s outermost header that is you re back in the third column Figure 4 1 Calling Order Dependency for Message Dequeue Routines mtalnit i mtaDequeueStart mtaDequeueRecipientNext mtaDequeueRecipientDisposition
299. ue is returned and mta errno is set to indicate the error status code The following table lists the error status codes and gives a description of each Error Status Codes Description MTA BADARGS A NULL value was supplied for the dctx call argument or an invalid decode context was supplied for dct x MTA NOSUCHITEM An invalid value was supplied for the item call argument Messaging Server 6 2005Q1 MTA Developer s Reference 150 mtaDecodeMessagePartCopy Example printf The message part s character set is s n mtaDecodeMessageInfoString dctx MTA DECODE CCHARSET NULL NULL mtaDecodeMessagePartCopy Explicitly copy a message part to the message being written Syntax int mtaDecodeMessagePartCopy mta decode t dctx int item code Arguments Arguments Description dctx A decode context created by mt aMessageDecode item code Reserved for future use A value of zero must be supplied for this argument Description When an output routine is used in conjunction with mtaDecodeMessage the inspection routine can explicitly request that the current message part be copied to the output destination After the inspection routine calls mtaDecodeMessagePartCopy it will no longer be called for that message part If the inspection routine is called with a data type of MTA DATA NONE the message part copy is implicitly done even if the inspection routine does not call either mtaDecodeMessageP
300. ui nensresxehhsrimce es peda 263 MIA SUBADDRESS e 605804 9 RRRRI ED a ECCE 263 Sable 264 o cedunt Spe MEA SUBIBGT Ax A ERE EE IS E OE WU re PIT RR DI Pd us 264 MTA TO Lerokeesegce MTA USER iine ehe ernest tema eem a da iate we omen 264 Appendix A Error Status Codes Summary 2206151151 265 GIGSSARY oes Iunio demise cdas 269 IndeX Aga 271 Contents 9 10 Messaging Server 6 2005021 MTA Developer s Reference Preface This manual describes the Sun Java System Messaging Server 6 200501 Message Transfer Agent MTA Software Development Kit SDK and Callable Send facility Topics covered in this chapter include e Who Should Use This Book e Before You Read This Book e How This Book Is Organized e Conventions Used in This Book Related Documentation e Accessing Sun Resources Online e Contacting Sun Technical Support e Related Third Party Web Site References Sun Welcomes Your Comments Who Should Use This Book While this document is primarily intended for system programmers writing mail software system managers wishing to become more familiar with the inner workings of the MTA may also benefit from a casual reading of this manual Programmers wishing to write gateways or channels should use the MTA SDK Programmers writing code merely to send mail will probably find the Callable Send facility sufficient for their needs Before You Read This Book Before You Read This Book
301. ut or not If it is not copying the part to the output the inspection routine must call mtaDecodeMessagePartDelete That call will either delete the part entirely or optionally replace it with caller supplied content Calling mtaDecodeMessagePartCopy makes the copy operation explicit if neither routine is called then the part will be implicitly copied to the message being output When using an output routine the inspection routine may call mtaDecodeMessagePartDelete Or mtaDecodeMessagePartCopy at any time It is not necessary to wait until the inspection routine is called with a data type of MTA DATA NONE For instance a virus scanner may want to discard a part when it sees that the part s content type indicates an executable program However once either of these routines is called the inspection routine will not be called any further for that message part Dequeue Context The message to be decoded is supplied by either a dequeue context or a caller supplied input routine When using a dequeue context observe the following points e Specify MTA DECODE DO for the input type call argument e Pass the dequeue context from mtaDequeueStart as the input argument The recipient list of the message being dequeued must have already been read by mtaDequeueRecipientNext before calling mtaDecodeMessage mtaDequeueMessageFinish must not yet have been called for the dequeue context e After using a dequeue cont
302. utines a channel program can process its queue of messages accessing the message s envelope information and message content This chapter discusses the following dequeuing topics How Dequeuing Works on page 50 Basic Dequeuing Steps on page 50 Caller Supplied Processing Routine on page 51 The process message Routine on page 54 A Simple Dequeue Example on page 56 Processing the Message Queue on page 60 The process done Routine on page 62 A Complex Dequeuing Example on page 63 Intermediate processing channels on page 71 Intermediate Channel Example on page 73 Thread Creation Loop in mtaDequeueStart on page 80 Multiple Calls to mtaDequeueStart on page 82 Calling Order Dependencies on page 82 49 How Dequeuing Works How Dequeuing Works Channel programs wishing to dequeue messages from the MTA must associate themselves with a specific MTA channel or channels Without this information the MTA SDK does not know which channel queue to draw messages from This information can be provided implicitly with the PMDF CHANNEL environment variable or explicitly by specifying the name of the MTA channel to process when calling mtaDequeueStart The dequeue process is initiated by calling the routine mtaDequeueStart A key piece of required information passed to mtaDequeueStart is the address of a caller supplied routine designed to process a single message This routine will be repeat
303. utput destination for the resulting message This directs mtabecodeMessage to output the resulting parsed message to the message being enqueued less any harmful attachments that are explicitly deleted by the inspection routine The routine decode inspect is supplied as the inspection routine If the call to mtaDecodeMessage fails the CHECK macro causes the queued message to be deferred and the message enqueue to be cancelled Chapter 5 Decoding Messages 107 A Simple Virus Scanner Example 9 After a successful call to mtaDecodeMessage the message enqueue is committed It is important that this be done before committing the dequeue If the operation is done in the other order dequeue finish followed by enqueue finish then mail may be lost For example the message would be lost if the dequeue succeeds and then deletes the underlying message file before the enqueue and then the enqueue fails for some reason such as insufficient disk space 10 The inspection routine decode inspect This routine checks the MIME header lines of each message part for indication that the part may contain harmful content 11 Message parts with harmful content are discarded with a call to mtaDecodeMessagePartDelete The discarded message part is replaced with a text message part containing a warning about the discarded harmful content 12 Message parts with safe content are kept by copying them to the output message with mtaDecodeMess
304. value of the MTA option MAX INTERNAL BLOCKS An error occurred while writing to a disk file Typically this will be the result of insufficient disk space or a file system error This error is only reported when writing message files either temporary files or writing them in the channel queue directories An error occurred while attempting to open a disk file In regards to channel option files this indicates that the channel option file exists but cannot be opened Usually this is caused by insufficient access rights or a file system error This error may also be returned when the MTA SDK is initialized and an MTA configuration file cannot be opened Again this usually indicates a problem with permissions or the file system Use the imsimta test rewrite utility to obtain additional diagnostic information That utility often reports the name of the underlying configuration file associated with the error A network read or write error has occurred This error is associated with message dequeue processing and indicates that a communication error has occurred while attempting to contact or exchange information with the MTA Job Controller Ensure that the Job Controller is running Generic error message This error message is issued in a variety of situations In all cases it indicates that the attempted call has failed Consult the routine s description for an interpretation specific to the called routine Also consider enabling MTA SD
305. vate context passed as ct x1 to mtaDequeueStart dq_ctx A dequeue context created by mtaDequeueStart and representing the message to be processed by this invocation of the process message routine env from A pointer to the envelope From address for the message to be processed Since Internet messages are allowed to have zero length envelope From addresses this address can have zero length The address will be NULL terminated env from len The length in bytes of the envelope From string This length does not include any NULL terminator When a processing thread first begins running it sets the value referenced by ctx2 to NULL This assignment is made only once per thread and is done before the first call to the process message routine Consequently on the first call to the process message routine by a given execution thread the following test is true ctx2 NULL That test will remain true until such time that the process message routine itself changes the value by making an assignment to ctx2 If the process message routine needs to maintain state across all calls to itself by the same processing thread it can allocate memory for a structure to store that state in and then save a pointer to that memory with ctx2 The following code snippet demonstrates this int process message void ctx2 void ctxl const char env from Size t env from len struct our_state_t state state our state t ct
306. x2 if state First call for this thread Allocate a structure in which to store the state information x state our state t calloc 1 sizeof our state t if state return MTA ABORT ctx2 void state Chapter 4 Dequeuing Messages 55 A Simple Dequeue Example Set any appropriate initial values for the state structure By For a sample process message routine see the example code in the section that follows A Simple Dequeue Example The program shown in Code Example 4 1 constitutes a simplified batch SMTP channel that reads messages from a message queue converting each message to batch SMTP format and writes the result to stdout If the conversion is successful then the message is dequeued otherwise it is deferred Some lines of code are immediately preceded by a comment of the format See explanatory comment N where N is a number The numbers are links to some corresponding explanatory text in the section that follows this code see Explanatory Text for Numbered Comments on page 69 Find the sample output in Output from the Simple Dequeue Example on page 60 Code Example 4 1 A Simple Dequeue Example dequeue simple c A simple dequeue example write BSMTP to stdout x include lt stdio h gt include lt stdlib h gt include mtasdk h static mta dq process message t process message int main int ires Initialize t
307. xt NOTE An explicitly specified channel name will take precedence over a channel name specified with a dequeue context As part of initiating a message submission item codes may be used to specify additional envelope information for the message as well as select non default values for MTA parameters that influence message enqueue processing The following table lists the items codes for this routine their additional arguments and gives a description of each Additional Arguments Description TA ALIAS EXPAND None When this item code is specified each envelope recipient address is allowed to undergo alias expansion for example mailing list expansion This is the default behavior TA ALIAS NOEXPAND None Use of this item code inhibits alias expansion for the envelope recipient addresses The default behavior is to permit alias expansion None Inhibit sorting of the envelope recipient list in the message copies written to the MTA channel queues By default the envelope recipient address list is sorted Use this option if it is imperative that the envelope recipients be processed in some specific order Maintaining the order requires control of all MTA channels that the message will pass through None Allow the envelope recipient list to be sorted in the message copies written to the MTA channel queues This is the default behavior mtaEnqueueStart Item Codes TA_ADR_NOSORT MTA_ADR_SORT 196 Messaging Serv
308. y begins processing the queued messages Message Processing Procedure To process queued messages a processing thread takes the following steps 1 The thread sets ctx2 to have the value NULL ctx2 NULL For information on the process message arguments see process_message Routine on page 178 2 The thread communicates with the Job Controller to obtain a message file to process If there are no more message files to process then go to Step 9 Chapter 6 MTA SDK Reference 7 3 For the message file the thread creates a dequeue context that maintains the dequeue processing state for that message file 4 The thread then invokes the caller supplied process message routine passing to it the dequeue context created in Step 3 for example istat process message amp ctx2 ctxl amp dq ctx env from env from len For a description of the process message routine see process message Routine on page 178 5 The process message routine then attempts to process the message ultimately removing it from the channel s queues or leaving the message file for a later processing attempt 6 IfmtaDequeueMessageFinish was not called before the process message routine returned then the queued message is deferred That is its underlying message file is left in the channel s queue and a later processing attempt is scheduled 7 The dequeue context is destroyed 8 Ifthe process message routine did not return the MTA ABORT st

Sun Java System Messaging Server 6 2005Q1 MTA Developer`s

Contents

Download Pdf Manuals

Related Search

Related Contents