MailSetField

The MailSetField function is used to add, update, or delete fields from the message header.

Syntax

BOOL MailSetField (MailMsg*pmm, LPWSTR szName, LPCWSTR szVal);

At a Glance

Header file:	Msgstore.h
Platforms:	H/PC
Versions:	1.0 and later

Parameters

pmm: Mail message containing the header entry to be changed.
szName: Pointer to a string containing the name field of the header entry to be added, deleted, or changed. When looking for a match, this parameter can be any combination of uppercase and lowercase letters because the name field is not case-sensitive.
szVal: Pointer to the new value for the field. If this parameter is NULL, the entry is deleted from the header string.

Return Values

This function returns TRUE if successful; FALSE if it fails. For extended error information, use MailError or MailErrorMsg.

Remarks

The MailSetField function searches the header (that is, the pwcHeaders field) of the MailMsg structure in memory. Before calling MailSetField, the message must be retrieved from the message store by calling MailGet, MailFirst, or MailNext.

The pwcHeaders member of the MailMsg structure points to the message's header string. The header consists of entries made up of two fields: a name, and an associated value. The name fields are separated from the value fields by a NULL character, and the entries are separated from each other by a NULL character. The header string is terminated with two consecutive NULL characters.

If a matching name field is not found in the message store, the entry is added to the header. If the entry name is found, the value field is changed to the new value passed in. If the value field being passed in is NULL and the entry name exists in the header, the entry is deleted.