PMDF Programmer's Reference Manual
Previous Next Contents Index

PMDFreceiptControl

Control the generation of read and delivery receipts.

PASCAL

status = PMDF_receipt_control

(nq_context, read, delivery, read_comment, delivery_comment, suppress_receipts)

argument information
Argument Data type Access Mechanism
nq_context context pointer read/write reference
read signed longword read value
delivery signed longword read value
read_comment boolean read value
delivery_comment boolean read value
suppress_receipts boolean read value

C

status = PMDFreceiptControl

(nq_context, read, delivery, read_comment, delivery_comment, suppress_receipts)

argument information 


int PMDFreceiptControl(PMDF_nq **nq_context, 
                       int       read, 
                       int       delivery, 
                       int       read_comment, 
                       int       delivery_comment, 
                       int       suppress_receipts)

Arguments

nq_context

A message enqueue context created with PMDFstartMessageEnvelope.

read

The value -1, 0, or +1. See the Description for details.

delivery

The value -1, 0, or +1. See the Description for details.

read_comment

If true then read receipt request comments will be honored; otherwise, read receipt request comments will be ignored.

delivery_comment

If true then delivery receipt request comments will be honored; otherwise, delivery receipt request comments will be ignored.

suppress_receipts

If true then any read or delivery receipt request headers will be removed from a message's header prior to enqueuing it. If false, then read and delivery receipt headers will not be removed if present.

Description

PMDFreceiptControl can be called to set or alter the nature of the read and delivery receipt headers which PMDF can generate. The settings established by PMDFreceiptControl will only affect the specified message enqueue context and can be changed with further calls to PMDFreceiptControl. By calling PMDFreceiptControl prior to each call to PMDFaddRecipient, the receipt handling behavior can be altered on a per address basis. It is important to keep in mind that when a message with multiple recipients is enqueued, multiple copies of that message can actually be created. Each copy differing in the contents of the message envelope and message header. In this way, it is possible to enqueue a message which will have receipt requests for some addressees but not others. A copy is made for those addressees requiring read receipt requests, another copy for those requiring delivery receipt requests, a third for those requiring both, and another for those requiring neither. Actually, it is even more complicated than this as different receipt request addresses can appear. The read and delivery arguments have default values of 0. These two arguments set the default receipt generation behavior:
  1. By default, if no other mechanism causes the creation of a read [delivery] receipt request, then an explicit "Read-receipt-to: <>" ["Delivery-receipt-to: <>"] header line is added to the message header. This has the effect of blocking any read [delivery] receipts from being returned to the message's originator.
  2. By default, no read [delivery] receipt request headers are added to the message header.
  3. By default, a read [delivery] receipt request header is added to the message header. The return address used for the header is that of the message's originator (envelope "From:" address) unless some other address has been selected with PMDFsetReceiptAddresses.
The read_comment and delivery_comment arguments control whether or not comment strings in "To:", "Cc:", and "Bcc:" addresses can be used to request a read or delivery receipt from that particular addressee. By default, such comments are ignored. To honor comments requesting read [delivery] receipts, specify a true value for read_comment [delivery_comment]; to ignore comments requesting read [delivery] receipts, specify a false value for read_comment [delivery_comment]. See the discussion of read and delivery receipt requests in the PMDF System Manager's Guide for further details on the use of comment strings in addresses as receipt requests. Finally, the suppress_receipts argument can be used to forcibly strip any or all receipt requests from a message's header. If suppress_receipts is true, then this stripping will always be done and will override any other mechanism for specifying receipt requests. If suppress_receipts is false, then such blind stripping will not be performed and the other mechanisms will be allowed to function. This is the default case.

Return Values

PMDF__OK Normal, successful completion.
PMDF__BADCONTEXT Illegal or corrupt context. No settings made or changed.

Previous Next Contents Index