String-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.

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 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: