Programmer's Guide:
Containment in an eRoom

Many SAAPI objects act as containers of other objects. For example, Polls contain Ballots, Ballots contain Votes, and Topics contain Comments and Polls. This section focuses on those containers that can contain principal items. These Container objects implement the IERUContainer interface, and include Discussion Page, Folder Page, Inbox Page, List Page, Mail Page, Note Page, Poll Page, Table Page, Topic Page, and Version Page.

An easy way to remember which objects implement IERUContainer is that in the eRoom user interface, the page for that object contains an "item box", a list box that displays contained items either as large icons, small icons, or as a multi-column detailed list. (Some pages only show the large icon view.) The shape and location of the item box varies depending on the page, but the concept is the same.

These container objects share the following capabilities:

  • You can get a list of the principal items they contain.

  • You can create new principal items within them.

  • You can copy or move existing principal items to them.

Some containers limit what kinds of principal items can be created in them, and some principal items can only appear in certain types of containers:

  • Discussion Pages can only contain Topic Pages (and Topic Pages can only reside in Discussion Pages)

  • Version Pages can only contain Files

  • Inbox Pages can only contain Mail Pages (and Mail Pages can only reside in Inbox Pages)

Getting the list of child items in a container

Enumerating the children of a container is a straightforward process: Simply use the Items property of the IERUContainer interface.

Sub ProcessContainer(Container as IERUContainer)
Dim Item as IERUItem

For Each Item in Container.Items
  'Do something with the child item
  Debug.Print Item.Name
Next
End Sub

Creating child items

To create a principal item inside a container, use one of the type-specific Create methods defined in the IERUContainer interface. Many of these methods take an input parameter to initialize a rich text property, and an associated parameter that indicates whether the value for the rich text parameter has been supplied as HTML or plain text. In addition, many of these methods take a parameter called CreateOptions, which lets you provide flags or initialization. Different methods accept different flags, so consult the reference help topics for information on specific methods. To supply more than one flag, you should logically OR the values from the ERUCreateOption enum. To specify no flags, use the value erCreateOptNone.

For example, the following example creates a Folder Page within a container:

'Assume MyContainer is already initialized to refer
'to an object that implements IERUContainer
Dim NewFolder as IERUItem
Set NewFolder = MyContainer.CreateFolder("New Folder Page",
"This is a Folder Page",
erFormatPlainText,
erCreateOptShowDescription | erCreateOptShowComments)

Moving, copying, deleting, and restoring items

To move or copy a principal item from one container to another, you must call the MoveTo or CopyTo method on the object, supplying the destination container as an argument to the call. The logged-in user must have "can edit" privileges on an object in order to move it. To copy an object, the logged-in user only needs "can open" privileges on the object. After you move an object, it has the same access control state that it had before you moved it, except that its new container may restrict access to it. After you copy an object, the copy of the source object in the destination container has a "can edit" list set to the user who performed the copy, and a "can open" list set to any member who can get to it (erScopeInheritOpenAccess). Furthermore, if the source object is marked "read only" or "reserved for editing", these states are not preserved in the new copy.

You do not delete an item through its container. To delete an item, call the Delete method on the item that you want to delete. Note that the user interface has a concept of a "wastebasket" that holds the contents of the last item or group of items deleted, and lets a user restore the last item deleted from this wastebasket. SAAPI does not employ this technique; when you delete an item through SAAPI, it is permanently deleted. Furthermore, SAAPI does not provide a way to restore an item that was deleted (sent to the wastebasket) through the user interface.

Name Uniqueness Rules

All Principal Items at the same level of containment in an eRoom must have unique names. When calling any of the "Create" methods in IERUContainer, you must specify a unique name or include the value erCreateOptMakeNameUnique in the set of flags passed via the CreateOptions parameter; otherwise the error EROOM_E_DUPLICATENAME will be returned. The CopyTo, MoveTo, and RouteTo methods in IERUItem work similarly, except that the flags to use are erCopyFlagMakeNameUnique, erMoveFlagMakeNameUnique, and erRouteFlagMakeNameUnique, and the parameters are CopyFlags, MoveFlags, and RouteFlags, respectively.

When you perform one of these operations and request name uniqueness by supplying the appropriate flag, eRoom will check for name uniqueness within the destination container. If there is a name conflict, the object's name will be modified according to the following rules:

  • When creating, moving or routing objects, names are made unique by appending " (n)", where n is the first number greater than 1 that is not in use in that container. Files will have the " (n)" appended to the basename of the file, leaving the extension intact.

  • When copying objects, names are made unique first by prepending "Copy of" to the name, and if that is not sufficient to achieve uniqueness, by prepending "Copy (n) of" to the name instead.