Top-Level Objects

Top-Level Objects

A top-level object is one that can be created directly by your code, without having to derive it from any other object. Currently, the only top-level object in CDO is the Session object. Other objects are accessible only through the Session object.

You can create a Session object either through early binding:

      Dim objSession As MAPI.Session
      Set objSession = CreateObject ("MAPI.Session")
      objSession.Logon
 

or through late binding:

      Dim objSession As Object
      Set objSession = CreateObject ("MAPI.Session")
      objSession.Logon
 

and then use the Logon method to initiate a session with MAPI. You cannot access any other object, or even the Session object's properties or methods, until you log on. The only exception to this rule is the Session object's SetLocaleIDs method.

Generally, early binding is preferable, because it enforces type checking and generates more efficient code. Note that you specify "MAPI.Session" instead of just "Session" in order to distinguish a MAPI session from other types of sessions available to a Visual Basic program through other object libraries.

Early binding is not supported in CDO Library versions previous to 1.1.

C/C++ programmers use globally unique identifiers (GUIDs) for these objects, defined in the type library for the CDO Library. The following C++ code fragment demonstrates how to create a Session object and call its Logon method:

// create a Session object and log on using IDispatch interface
// to the CDO library
#include <ole2.h>
#include <stdio.h>
#include <stdlib.h>  // for exit
#define dispidM_Logon 119  // get constants for all props, methods
// allows you to save cost of GetIdsFromNames calls
// can generate yourself by calling GetIdsFromNames for all
// properties and methods
// GUID values for Session defined in the type library
static const CLSID GUID_OM_SESSION =
{0x3FA7DEB3, 0x6438, 0x101B, {0xAC, 0xC1, 0, 0xAA, 0, 0x42, 0x33, 0x26}};
void main(void)
{
HRESULT hr;

/* interface pointers */
LPUNKNOWN punk = NULL; // IUnknown *; used to get IDispatch *
DISPPARAMS dispparamsNoArgs = {NULL, NULL, 0, 0};
VARIANT varRetVal;
IDispatch * pSession;

    //Initialize OLE.
    hr = OleInitialize(NULL);
        printf("OleInitialize returned 0x%lx\n", hr);
    VariantInit(&varRetVal);
// Create an instance of the CDO Library Session object
// Ask for its IDispatch interface.
    hr = CoCreateInstance(GUID_OM_SESSION,
                          NULL,
                          CLSCTX_SERVER,
                          IID_IUnknown,
                          (void FAR* FAR*)&punk);
    printf("CoCreateInstance returned 0x%lx\n", hr);
    if (S_OK != hr)
        exit(1);
    hr = punk->QueryInterface(IID_IDispatch, (void FAR* FAR*)&pSession);
    punk->Release();        // no longer needed; release it
    printf("QI for IID_IDispatch returned 0x%lx\n", hr);
    if (S_OK != hr)
        exit(1);
// Logon using the session object; call its Logon method
    hr = pSession->Invoke(dispidM_Logon, // value = 119
                          IID_NULL,
                          LOCALE_SYSTEM_DEFAULT,
                          DISPATCH_METHOD,
                          &dispparamsNoArgs,
                          &varRetVal,
                          NULL,
                          NULL);
    printf("Invoke returned 0x%lx\n", hr);
    printf("Logon call returned 0x%lx\n", varRetVal.lVal);
// do other things here...
// when done, release the Session dispatch object and shut down OLE
    pSession->Release();
    OleUninitialize();