SAMPLE: OLE Automation Collection

Last reviewed: October 23, 1996
Article ID: Q107546

The information in this article applies to:

Microsoft OLE Libraries for Windows and Win32s, version 2.0

Microsoft OLE Libraries, included with:

    - Microsoft Windows NT, versions 3.5 and 3.51
    - Microsoft Windows 95

SUMMARY

COLLECT demonstrates how to create an OLE automation collection object.

You can find COLLECT.EXE (size: 38484 bytes) 
                        , a self-extracting file, on the following

services:

Microsoft's World Wide Web Site on the Internet

      On the www.microsoft.com home page, click the Support icon.
      Click Knowledge Base, and select the product.
      Enter kbfile COLLECT.EXE (size: 38484 bytes) 
                              , and click GO!
      Open the article, and click the button to download the file.

Internet (anonymous FTP)

      ftp ftp.microsoft.com
      Change to the \softlib\mslfiles folder.
      Get COLLECT.EXE. (size: 38484 bytes)

Microsoft Download Service (MSDL)

      Dial (206) 936-6735 to connect to MSDL.
      Download COLLECT.EXE. (size: 38484 bytes)

MORE INFORMATION

The collection object implements the following methods and properties: Add Method, Count Property, Item Property, NewEnum Property, and Remove Method.

Error handling in the collection object involves raising exceptions. CreateStdDispatch does not allow exceptions to be raised, so the collection object implements the IDispatch interface using DispGetIDsOfNames and DispInvoke.

Add Method

Description:     Adds the indicated item to the collection. If an object
                 is created, it should be returned.
Arguments:       Varies. It can be a pointer to the object that is to be
                 added or it can the information required to create the
                 object.
Return type:     Varies. If no object is created, the return type should
                 be void. If an object is created, the return type should
                 be VT_DISPATCH.

Note: The Add method is not appropriate for all collections, so it is not required. For many application-created collections, objects are automatically added to the collection for the user.

Count Property

Description:     Returns the number of items in the collection. Read-only
                 property.
Arguments:       None.
Return type:     VT_I4.

Item Property

Description:     Returns the indicated item in the collection.
Argument:        Specifies the index. Some collections allow various types
                 of indexing. For example, this sample allows an integer or
                 string to be specified as an index.
Return type:     VT_DISPATCH.

Note: Item is the default value for the object, so it should have the special DISPID, DISPID_VALUE. MkTypLib automatically assigns this DISPID if the default attribute is specified in the ODL file.

_NewEnum Property

Description:     Returns an enumerator that supports IEnumVariant for the
                 items currently in the collection. Read-only property.
Arguments:       None.
Return type:     VT_UNKNOWN.

Note: NewEnum will not be accessible to users and must have the restricted attribute in the ODL file. The NewEnum method must have a special DISPID, DISPID_NEWENUM. The defining characteristic of a collection is the ability for a user to iterate over the items in it. Some languages will have built- in support for collections. The NewEnum method allows an OLE automation controller to support "for each" iteration over a collection:

   For Each Item In Collection
   Debug.Print Item.Text
   Next Item

OLE automation controllers that support "for each" iteration will call the NewEnum method on the collection object and then QueryInterface on the resulting IUnknown to get the desired IEnumVariant.

Remove Method

Description:     Removes the specified item from the collection.
Argument:        Specifies the index. Some collections allow various types
                 of indexing. For example, this sample allows an integer
                 or string to be specified as an index.
Return type:     void.

Note: The object is not deleted. It is simply removed from the collection. Remove should support the same kinds of indexing as the Item() method for the same collection. The Remove method is not appropriate for all collections, so it is not required. For many application-created collections, objects are automatically removed the collection for the user.

To Run

The collection sample application object exposes the following:

   ProgID :  Collection.Application

   Method and Property Names     Notes
   -----------------------------------------------------------
   [App Object]
   Collection  (read only prop)  Returns empty collection.
   New Item    (method)          Creates and returns new item.

   [Item Object]
   Text        (default prop)    Sets and returns string.

   [Collection Object]
   See above for exposed properties and methods.

Update the path in HELLO.REG to the current location of the object and the type libraries.

To Compile

Requires OLE version 2.01 or later.

Include device=vmb.386 in the [386Enh] section of SYSTEM.INI. Note that vmb.386 can be found in \OLE2\BIN. Run WXSERVER.EXE from \OLE2\BIN before running the makefile.

Additional reference words: 2.00 3.50 4.00 softlib
KBCategory: kbole kbfile kbwebcontent
KBSubcategory: LeTwoAto

THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.

Last reviewed: October 23, 1996
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.