Messages

A collection of Message objects.

Properties

The following table lists properties along with their access and descriptions.

Property

Access

Description

Application

R/O

Application. The number of objects in this collection.

Count

R/O

Long. The number of objects in this collection.

_NewEnum

R/O

Enumeration object. Implements IEnumVARIANT. For Windows only.

Parent

R/O

Folder. The Folder object that owns this collection.

Methods

Message Add([String ClassName], [Enum (egwDraft, egwPersonal) ObjType])

Creates a new Message and links it to the folder that owns this collection. ClassName is a C3PO class name that specifies the kind of message to create. If ClassName is omitted, a mail message (GW.MESSAGE.MAIL) is assumed.ObjType specifies whether to create a draft or personal message. If ObjType is omitted, egwDraft is assumed.

Message Add([String ClassName], [Object Referent], [DocumentReferenceTypeConstants Version])

Creates a new Message and links it to the folder that owns this collection.

  • ClassName is a C3PO class name that specifies the kind of message to create. If ClassName is omitted, a document reference (GW.MESSAGE.DOCUMENTREFERENCE) is assumed. .

  • Referent is the object the new message refers to. For GroupWise, Referent applies only to messages of class GW.MESSAGE.DOCUMENTREFERENCE and its subclasses where Referent must be either a Document or DocumentVersion object. Referent is required when creating a document reference.

  • Version controls how the document reference refers to the document or document version. If Referent is a Document object and Version is omitted, egwCurrent is assumed. If all parameters are omitted, the first version of the Add method is assumed.

Message Add(Message Message)

Adds an existing Message object to this collection and links it to the folder that owns this collection. A message can exist in multiple folders.

  • If there is a corresponding Trash entry, it is automatically deleted.

  • The Message object used as a parameter must be of type VARIANT. If early binding is used to dimension the message object, an error might result.

  • If Message and the folder that owns this collection do not belong to the same account, an exception is thrown.

When the Messages collection represents a shared folder, calling this method can cause a copy of the message to be added. That is, the returned message may be a copy of the message being added rather than simply returning the parameter passed in. This is because moving an item to a shared folder often results in the item being copied to a unique "prime" database. As a result, rather than a single message in two folders, there are two unique messages, each in a unique folder.

Message AddExistingMessage (String SenderDisplayName, String SenderEmailAddress, String SenderEmailAddressType, Date CreationDate, MessageBoxTypeConstants MessageBoxType, MessageStatusConstants MessageStatus, MessagePriorityConstants MessagePriority, MessageSecurityConstants MessageSecurity, [VARIANT DraftMessage], [VARIANT LastModificationDate])

Adds a Message to the database, but does not send the message. The GroupWise system treats these like InBox or OutBox items but does not try to send them. This method is useful for synchronized email from a Palm PDA or POP3 mail from another account.

The parameters are as follows:

  • SenderDisplayName—The display name of the original sender. If this is NULL, no display name is added.

  • SenderEmailAddress—The email address of the original sender. If this is NULL, no email address is added.

  • SenderEmailAddressType—The type of email address. If NULL, no address type is added.

  • CreationDate—The date the message was created. This value is reported as the actual creation date of the message, not the time of the call to AddExistingMessage.

  • MessageBoxType—The type of message (see Section 4.30, MessageBoxTypeConstants). If not specified (zero), it is a Draft message.

  • MessageStatus—A bitmask that defines the status of the message (see Section 4.33, MessageStatusConstants).

  • MessagePriority—The priority of the message (see Section 4.31, MessagePriorityConstants). If not set (zero) or set to an undefined value, egwNormal is assumed.

  • MessageSecurity—The security of the message (see Section 4.34, MessageSecurityConstants).

  • DraftMessage (optional)—Points to a VARIANT structure of type VT_DISPATCH (all other types are ignored). A DIGWMessage pointer pointing to a Message object must be placed in the VARIANT data or an error is returned.

  • LastModificationDate (optional)—Points to a VARIANT structure of type DATE (VT_EMPTY or VT_ERROR is ignored). This date is stored as the date and time of the last modification of the message. If this VARIANT is ignored or there is an error in obtaining the modification date, no modification date is stored for the message.

Message AddExistingMessageExt( String SenderDisplayname, String SenderEmailAddress, String SenderEmailAddressType, Date Creation Date, MessageBoxTypeConstants MsgBoxType, MessageStatusConstants MsgStatus, MessagePriorityConstants MsgPriority, MessageSecurityConstants MsgSecurity, [VARIANT DraftMsg], [VARIANT LastModificationDate], [VARIANT DeliveryDate])

Adds a message to the databse, but does not sent the message. The GroupWise sysytem treates these like InBox or OutBox items but does not try toi send them, This method is useful for synchronized email from a Palm, PDA, or POP3 mail from another account.

The parameters are as follows:

  • SenderDisplayName—The display name of the original sender. If this is NULL, no display name is added.

  • SenderEmailAddress—The email address of the original sender. If this is NULL, no email address is added.

  • SenderEmailAddressType—The type of email address. If NULL, no address type is added.

  • CreationDate—The date the message was created. This value is reported as the actual creation date of the message, not the time of the call to AddExistingMessage.

  • MessageBoxType—The type of message (see Section 4.30, MessageBoxTypeConstants). If not specified (zero), it is a Draft message.

  • MessageStatus—A bitmask that defines the status of the message (see Section 4.33, MessageStatusConstants).

  • MessagePriority—The priority of the message (see Section 4.31, MessagePriorityConstants). If not set (zero) or set to an undefined value, egwNormal is assumed.

  • MessageSecurity—The security of the message (see Section 4.34, MessageSecurityConstants).

  • DraftMessage (optional)—Points to a VARIANT structure of type VT_DISPATCH (all other types are ignored). A DIGWMessage pointer pointing to a Message object must be placed in the VARIANT data or an error is returned.

  • LastModificationDate (optional)—Points to a VARIANT structure of type DATE (VT_EMPTY or VT_ERROR is ignored). This date is stored as the date and time of the last modification of the message. If this VARIANT is ignored or there is an error in obtaining the modification date, no modification date is stored for the message.

  • DeliveryDate (optional)—Points to a VARIANT structure of type DATE (VT_EMPTY or VT_ERROR is ignored). This date is stored as the date and time this message was delivered to the user. If this VARIANT is ignored or there is an error in abtaining the date, no delivery date is stored for the message.

NOTE:The AddExistingMessage and AddExistingMessageExt methods store a restore date on the message. This resotre date will prevent the new message from being auto purged or auto archived for 7 days. In addition, if the Smart purge feature is turned on, the restore date will prevent the message from being deleted from the Trash folder until it can be backed up or digested.

MessageList Find(VARIANT Condition)

Returns the MessageList collection containing the message matching the given Condition. Condition may be a string or a filter object. If condition is a string, it represents a filter expresion. See Section 5.0, Filter Expressions. If Condition is a filter object, it represents a saved filter.

Message Item(VARIANT Index)

DEFAULT. Returns the Message specified by Index. Index may be a Long or a string. If Index is a Long, returns the Message object located at the given Index in the collection. Valid indexes are 1 through Count, inclusive. Throws an exception if the Index is outside of this range. If Index is a string, returns the Message object whose MessageID is equal to Index.

Message Move(VARIANT Index, Messages Destination)

Moves the message specified by Index from this collection to the collection specified by Destination. Index may be a Long, a string, or a Message object. If the Message object represented by Index and the Messages collection represented by Destination do not belong to the same account, an exception is thrown.

  • If Index is a Long, it represents the Message object located at the given Index in the collection. Valid indexes are 1 through Count, inclusive. Throws an exception if the Index is outside of this range.

  • If Index is a string, it represents the Message object whose MessageID is equal to Index.

  • If Index is a Message object, it is the desired message.

When the Messages collection represents a shared folder, calling the Move method can cause a copy of the message to be added. That is, the returned message may be a copy of the message being added rather than simply returning the parameter passed in. This is because moving an item to a shared folder often results in the item being copied to a unique "prime" database. When this occurs, the original message (or link) is dissolved.

The Move method does not allow messages to be added to the Contacts folder or any Query folder. It allows messages with only a BoxType of egwOutgoing to be placed in the Sent Items systems folder.

The Move method allows any item to be placed into the Checklist folder. Placing any item in the Checklist folder gives the item the ability to have a Due Date, marks the item as Complete, and places the message in a specified spot.

Remove(VARIANT Index)

Removes the message specified by Index from this collection. Index may be a Long, a string, or a Message object. If Index is a Long, removes the Message object located at the given Index in the collection. Valid indexes are 1 through Count, inclusive.Throws an exception if the Index is outside of this range. If Index is a string, removes the Message object whose MessageID is equal to Index. If Index is a Message object, removes the given Message object from the collection.

SequenceChecklistItem(ChecklistSequenceConstants MoveWhere, VARIANT vrMessageToSequence, VARIANT vrMessageBefore, vrMessageAfter)

Moves the vrMessageToSequence item on the Master Checklist.

The three variant parameters: vrMessageToSequence, vrMessageBefore, and vrMessageAfter represent GroupWise Message objects. The three variants can be filled with a IGW_MESSAGE interface pointer, a BSTR holding the MessageID of the Message Object, or an integer with the Index into the Messages collection of the desired Message object.

If the MoveWhere constant is egwChecklistTop, the vrMessageToSequence is moved to the top of the Checklist. The vrMessageToSequence variant must hold a valid Checklist item. The vrMessageBefore and vrMessageAfter parameters are ignored.

If the MoveWhere constant specifies egwChecklist bottom, the vrMessageToSequence is moved to the bottom of the Checklist. The vrMessageBefore and vrMessageAfter parameters are ignored.

If the MoveWhere constant is egwChecklistBetween, the vrMessageToSequence is placed between the two messages represented by vrMessageBefore and vrMessageAfter. In this case, all three Variant parameters must point to valid Messages in the Checklist.

For the possible ChecklistSequence constants that are available, see Section 4.14, ChecklistSequenceConstants.

Remarks

When the Messages collection represents a query folder, calling the Add method will throw an exception.

A Messages collection is refreshed when its parent object is refreshed. When a Messages collection is refreshed, it updates the Message objects in the collection but does not recursively refresh the Message objects themselves.

To add an existing message:

  1. Add a Draft Message to the collection by calling Messages Collection::Add.

  2. Populate the Draft Message with Recipients, body text, subject, and other data.

  3. Call AddExistingMessage specifying the new Draft Message.

    IMPORTANT:If successful, the Draft Message is placed in the Trash folder.