3.51 Folder

A GroupWise message store folder.

3.51.1 Properties

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

Property

Access

Description

AllFolders

R/O

Folders collection. All folders directly or indirectly contained by this folder.

Application

R/O

Application. The Application object.

CalendarColor

R/W

Long. Of this is not the calendar folder or a sub calendar folder, an error will be returned. The RGB value that items in this calendar will be displayed in.

ContactsAddressBook

R/W

AddressBook. Returns or sets the Address Book associated with a Contacts folder. Note: This property is valid only on the Contacts folder. All other folders result in an error.

Description

R/W

String. The description of this folder.

Fields

R/O

Fields collection. The collection of user-defined fields for this folder.

FolderID

R/O

String. Unique folder ID. Persistent across sessions.

FolderRights

R/O

FolderRightsCollection. Access rights given to specific users.

Folders

R/O

Folders collection. The collection of sub-folders to this folder.

Messages

R/O

Messages collection. The collection of messages in this folder. Note: A Contacts folder is a shortcut to an Address Book. Calling for the Messages collection on the Contacts folder results in an error.

ModifiedDate

R/O

Date. The date and time this folder was last modified.

Name

R/W

String. The name of this folder.

The Name for the root folder is the User's Display Name, concatenated with the localized word for “Home.” For example, the root folder name for user John Doe is “John Doe Home.”

Your application might need to check the ObjType property of a folder to ensure that it is the true root folder. If it is the root folder, you can access the Owner property of the account, then retrieve the DisplayName of the user from the returned Address object (which is the same string that is used to name the root folder in previous GroupWise versions).

ObjType

R/O

Enum (FolderTypeConstants). The type of this folder.

Owner

R/O

Address. The user who owns this folder.

Parent

R/O

Object. The Folders collection that owns this folder, or if this is the root folder, the Account object that owns this Folder.

ParentFolder

R/O

Folder. The parent folder to this folder, or "Nothing" if this is the root folder.

Position

R/W

Long. The sequence number or position of this folder inthe folder list.

NOTE:All other sibiling folders will be resequenced automatically.

PublishCalendar

R/W

Boolean. TRUE if the sub-calendar can be published, FALSE otherwise.

PublishCalendarIncludeAttachments

R/W

Boolean. TRUE if attachments to the calendar items should be published to the web; else FALSE.

PublishCalendarIncludePrivateItems

R/W

Boolean. TRUE if items marked private should be published to the web; else False.

PublishCalendarTimePeriodEndDays

R/W

CalendarFolderPublishTimePeriodConstants. If the PublishCalendarTime Period is set to egwPublishLimitedCalendar, the number of days past today that will be published to the web; otherwise this value is ignored.

PublishCalendarTimePeriodStartDays

R/W

CalendarFolderPublishTimePeriodConstants. If the PublishCalendarTime Period is set to egwPublishLimitedCalendar, the number of days previous to today that will be published to the web; otherwise this value is ignored.

PublishEntireCalendar

R/W

Boolean. Set to TRUE if all Calendar contents can be published to the web; else set to FALSE.

Query

R/O

Query. The query associated with a query folder. Applies only to folders whose ObjType = egwQuery.

RSSCameFromIE7

R/W

Boolean. TRUE if RSS feed came from Internet Explorer 7.

RSSClearAllOnRefresh

R/W

Boolean. TRUE if all folder contents are removed, then refreshed from the RSS location.

RSSDoNotCheckImages

R/W

Boolean. TRUE if no warnings about images in items should be given to user.

RSSDownloadPage

R/W

Boolean. TRUE if RSS HTML page shoudl be downloaded.

RSSIsAggregator

R/W

Boolean. TRUE if folder is an RSS aggregator.

RSSIsRoot

R/W

Boolean. TRUE if folder is RSS root.

RSSLocation

R/W

String. The location this folder uses to read an RSS feed.

RSSUpdateFrequency

R/W

FolderUpdateFrequencyConstants. An enumerated value pointing out how often to check the SubscribeCalendarLocation for new items.

Shared

R/O

Enum (SharedFolderConstants). The folder’s shared status.

ShowInMainCalendar

R/W

Boolean. If this is not a sub-calendar folder, an error will be returned. If this is a sub-calendar folder, TRUE if the calendar contents will be combined with the main calendar folder; False otherwise.

SubscribeCalendarFrequency

R/W

FolderUpdateFrequencyConstants. An enumerated valuse poinintg out how often to check the SubscribeCalendarLocation for new items.

SubscribeCalendarLocation

R/W

String. The location this folder uses to read an RSS feed.

System

R/O

Boolean. TRUE for Cabinet, Calendar, Mailbox, Root, and Work In Progress folders.

3.51.2 Methods

Delete()

Removes this folder from its parent object, deletes this folder and its contained messages, and recursively deletes this folder’s subfolders and their contained messages. The deleted messages are added to the Trash. Any folders and messages not owned by this folder’s account are not deleted; only this account’s references to them are deleted.

MessageList FindMessages(VARIANT Condition)

Returns all messages in a folder that pass the filter in Condition. Condition can either be a string or a Filter object. If Condition is a string, it represents a filter expression (see Filter Expressions). If Condition is a Filter object, it represents a saved filter.

FindMessages is similar to the Find method in the Messages collection, except the Find method in the Messages collection instantiates all messages before applying the filter. To save the overhead of instantiating a messages collection, use this method when you do not already have a messages collection. Once you have a Messages collection, you can call its Find method without losing efficiency.

If the folder is a query folder, FindMessages returns an empty MessageList.

QuickMessages GetQuickMessagesCollection(Date StartDate, QuickMessagesCreationConstants eHowBuildList)

Returns a QuickMessages collection object. For a list of properties available, see QuickMessage.

The eHowBuildList parameter controls which message items are included in the collection. The following values are possible for eHowBuildList:

egwNewMessages

Messages items in this account that were created or received only since the StartDate parameter are included

egwModifiedMessages

Message items in this account that have been changed only since the StartDate parameter are included

egwAllMessages

Every message item in this account is added to the QuickMessages collection, and the StartDate parameter is ignored.

The QuickMessages collection should return message items quicker than other ways (such as the Messages collection, using the Messages Find method to retrieve a message list). It is very fast when returning new messages, but retrieving modified messages is somewhat slower. The slowest is to retrieve all messages from an account.

GetQuickMessagesCollection should be called only on a main account. Calling this method from a Proxy account results in an error. It also returns an error if called from the Contacts, Query, or Trash folder.

Messages in a folder that have been shared do not appear in the resulting QuickMessages collection. These folders are not part of the user's database and are outside of the account.

Account contains a similar method. However, the Folder object method uses messages that are in this specific folder only, whicle the Account object method looks through every message in the user's database.

NOTE:This method does not return hidden messages. Call the GetQuickMessagesCollectionExt method to return hidden messages.

QuickMessages GetQuickMessagesCollectionExt (Date StartDate, QuickMessagesCreationConstants, eHowBuildList, BOOL bIncludeHidden)

Returns a QuickMessages collection object. The bIncludeHidden parameter dictates whether Hidden messages are included with the returned collection.

The eHowBuildList parameter controls which message items are included in the collection. The following values are possible for eHowBuildList:

egwNewMessages

Messages items in this account that were created or received only since the StartDate parameter are included

egwModifiedMessages

Message items in this account that have been changed only since the StartDate parameter are included

egwAllMessages

Every message item in this account is added to the QuickMessages collection, and the StartDate parameter is ignored.

This method should return message items more quickly than other ways (such as using the AllMessages collection and querying objects with their Message Lists). Retrieving Modified Messages is slower than returning New Messages. Retrieving All Messages from an Account is the slowest.

Move(Folder DestFolder)

Moves this folder to the folder specified by DestFolder. In other words, makes this folder a sub-folder of DestFolder. The Mailbox, Calendar, and Query folders are invalid DestFolder values.

Refresh()

Forces this Folder object and its associated FolderRights and Query objects to reread property values from the message database.

3.51.3 Remarks

The PeekModeFlagConstants can be used by a Trusted Application to set teh appropriate statuses when a Message is opened. The following values are part of a bitmask and can be combined to form the set of flags that are automatically marked on a Message when in Peek Mode:

  • 0 egwNoPeekModeFlags
  • 1 egwPeekModeOpenedFlag
  • 2 egwPeekModeReadFlag
  • 4 egwPeekModeDownloadedFlag

When an Appointment is accepted, it is automatically moved to the Calendar folder. Also, personal Appointments and Tasks go into the Calendar folder by default.

To share a folder, create a FolderRights object for the user (see the Add method in the FolderRightsCollection). To unshare a folder, delete the user's FolderRights objects (see the Delete method in the FolderRights object). Only personal folders (ObjType = egwPersonalFolder) can be shared.

For an unshared folder (Shared = egwNotShared), the FolderRights collection is empty.

For a shared folder owned by the user (Shared = egwSharedOutgoing), the FolderRights collection contains one or more read/write instances of FolderRights objects, each of which grants access rights to a specific Address. For a shared folder owned by someone else (Shared = egwSharedIncoming), the FolderRights collection contains the FolderRights for all users.

When a Folder is refreshed, it recursively refreshes the Folders collection returned by its AllFolders property, its FolderRights collection, Folders collection, Messages collection, the Address object returned by its Owner property, and its Query object.

The list of System folders includes the Contacts, Sent Items, and Checklist folders.

The Contacts folder is a shortcut to an Address Book. In the GroupWise client, a user is free to add, delete, or modify any Address Book Entry. In the Object API, the Contacts folder returns an exception if it is asked for its Messages collection, or if a program attempts to move Messages into the folder.

In the place of the Messages Collection, use the ContactsAddressBook property to retrieve the Address Book that the Contacts folder is currently using. Then retrieve the AddressBookEntries collection from the AddressBook as the items in this folder.

By default, the Contacts folder works with the Frequent Contacts address book. To change the default setting, retrieve any GroupWise Personal AddressBook object and set the Contacts folder ContactsAddressBook property with this Address Book.

The Sent Items and Task List folders are not created by default. However, a GroupWise user can still create these folders.

The Sent Items system folder replaces the Sent Items query folder. Retrieving the Sent Items system folder Messages collection returns items Sent by this user to others that are also contained in the Mailbox, Sent Items, or Calendar folder.

NOTE:Unlike the Sent Items query folder, the Sent Items system folder does not do a Query to obtain the list of contents. This step should improve the response time when you are retrieving the Messages collection from this folder.

The Checklist folder contains a special group of Message items. These items have been moved into the Checklist folder, or these items remain in their folder but have been marked with the Show On Checklist flag. Please see the Appointment, DocumentReference, Mail, Note, Phone, Task, and SharedNotification objects for further Checklist features.

GroupWise 8.0 has added the ability to publish or subscribe calendars through a Web service. These properties allow a third party to modify the settings on an individual sub-calendar.

Calendar publishing is accomplished using a new Web Service. Any sub-calendar that is allowed will be published to the given location. Please see the calendar publishing web service documentation for further details.

On the other hand, subscription calendars settings are used only by GroupWise clients. Items are read from the given location, then displayed by GroupWise clients. No items are created in the GroupWise Database. As such, the Object API will return the subscription calandar, but the messages collection of that calendar will be empty.

NOTE:A GroupWise Administrator must enable calendar publishing and subscriptions before these properties can be used. If the administrator disables calendar publishing or subscriptions, all methods related to that feature will return an “Access Denied” error.