PMDF Programmer's Reference Manual
PMDF-PRM-6.0

Control the generation of read and delivery receipts.

VMS FORMAT

status = PMDF_receipt_control

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

C FORMAT

status = PMDFreceiptControl

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

int PMDFreceiptControl (nq_context, read, delivery, 
                        read_comment, delivery_comment, 
                        suppress_receipts) 
         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 PMDF_start_message_envelope.

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

PMDF_receipt_control may be called to set or alter the nature of the read and delivery receipt headers which PMDF may generate. The settings established by PMDF_receipt_control will only affect the specified message enqueue context and may be changed with further calls to PMDF_receipt_control. By calling PMDF_receipt_control prior to each call to PMDF_add_recipient, the receipt handling behavior may 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 may 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 may appear. The read and delivery arguments have default values of 0. These two arguments set the default receipt generation behavior:

• 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.
• By default, no read [delivery] receipt request headers are added to the message header.
• 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 PMDF_set_receipt_addresses. The read_comment and delivery_comment arguments control whether or not comment strings in To:, Cc:, and Bcc: addresses may 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 may 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.