Platform SDK: Exchange 2000 Server

SaveTo Method

[This is preliminary documentation and subject to change.]

Binds to and saves data into the item with the specified URL.

[Visual Basic,VBScript]
Sub SaveTo(
  ByVal SourceURL as String,
  ByVal ActiveConnection as Object,
  [ByVal Mode as ConnectModeEnum],
  [ByVal CreateOptions as RecordCreateOptionsEnum],
  [ByVal Options as RecordOpenOptionsEnum],
  [ByVal UserName as String],
  [ByVal Password as String]
)
[C++]
HRESULT SaveTo(
  BSTR SourceURL,
  IDispatch* ActiveConnection = 0,
  ConnectModeEnum Mode,
  RecordCreateOptionsEnum CreateOptions,
  RecordOpenOptionsEnum Options,
  BSTR UserName,
  BSTR Password
);
[IDL]
HRESULT SaveTo(
  [in] BSTR SourceURL,
  [in, defaultvalue(0)] IDispatch* ActiveConnection,
  [in, optional] ConnectModeEnum Mode,
  [in, optional] RecordCreateOptionsEnum CreateOptions,
  [in, optional] RecordOpenOptionsEnum Options,
  [in, optional] BSTR UserName,
  [in, optional] BSTR Password
);
SourceURL
The URL specifying where to save.
ActiveConnection
A reference to an existing ADO Connection object to use when saving. A new Connection (session) object is implicitly created if none is specified.
Mode
ADO defined access mode for the object. This value is always ORed with adModeReadWrite. That is, at least read-write access is required to save the item.
CreateOptions
Creation options for the new item. The values adFailIfNotExists and adOpenIfExists should not be used. If used, an E_INVALIDARG exception is raised.
Options
This specifies options flag(s) opening the source. Your setting is always ORed with adOpenSource.
Username
Used to pass a user name if needed for authentication.
Password
Used to pass a password if needed for authentication.

Remarks

The specified URL must identify a valid URL namespace that the OLE DB 2.5 root binder can resolve to a registered provider binder. Once resolved, the URL must conform to that provider binder's URL semantics.

The enumerated values and their semantic definitions are defined as part of the ADODB type library and documentation. Consult the ActiveX Data Objects (ADO) Version 2.5 documentation for a list of valid enumeration values and their intended purpose. Use of various enumerated values and their intended meaning is specific to a particular OLE DB 2.5 provider.

Restrictions on what types of data can be saved into a particular resource and how that data is handled by an implementation of the IDataSource interface is not part of this definition. Consult the appropriate COM class reference for further information.

Example

[Visual Basic]
Function CreateAndSaveMessageTo(URL1 as String) as CDO.Message

    Dim iFldr As New Folder
    Dim iDsrc As CDO.IDataSource
    Set iDsrc = iFldr
    
    ' Open private root folder:
    ' e.g. URL1 = "file://./backofficestorage/microsoft.com/MBX2/useralias/"
    iDsrc.Open URL1, , adModeReadWrite
    
    Dim Conn As ADODB.Connection
    Set Conn = iDsrc.ActiveConnection
    
    Dim iMsg As New CDO.Message

    ' This is not very enlightening, but its short for brevity...
    With iMsg
        .To       = "someone@microsoft.com"
        .From     = "another@microsoft.com"
        .Subject  = "Here is the subject"
        .TextBody = "Here is the text of the message"
    End With
    
    Set iDsrc = iMsg
    
    iDsrc.SaveTo "MySavedItems/item8.eml", _
                Conn, _
                adModeReadWrite, _
                adCreateOverwrite

    Set CreateAndSaveMessageTo = iMsg

End Sub
[C++,IDL]
/* Assume these headers:
 *
 * #import <msado15.dll> no_namespace
 * #import <cdoex.dll> no_namespace
 * #include <iostream.h>
 */

HRESULT SaveMessageToFolder(IMessage* pMsg, BSTR url) {


   IDataSource* pDsrc   = NULL;
   HRESULT hr = CoCreateInstance(__uuidof(Folder),
                        NULL,
                        CLSCTX_INPROC_SERVER,
                        __uuidof(IDataSource),
                        reinterpret_cast<void**>(&pDsrc));


   // for passing optional variants, we may need this
   _variant_t varOpt(DISP_E_PARAMNOTFOUND,VT_ERROR);
   
   /* 
   * Bind to web store root folder (private/messages)
   *  e.g. URL1 below is something like 
   * "file://./backofficestorage/microsoft.com/storename/username/"
   */

   hr=pDsrc->raw_Open( 
      url,
      NULL,
      adModeRead,
      adFailIfNotExists,
      adOpenSource,
      NULL,
      NULL
      );

   if(FAILED(hr)) {
      cerr << "Failed to open folder " << _bstr_t(url) << endl;
      pDsrc->Release();
      return hr;
   }

   /* 
   *  Get ActiveConnection for bound collection resource 
   *  (root of private folders for user)
   */
   _Connection* pConn = NULL;
   hr=pDsrc->get_ActiveConnection(&pConn);

   /*
   * Now use current active connection to create and
   * save another
   * message for the store
   */

   IDataSource* pDsrc2 = NULL;
   hr = pMsg->QueryInterface(__uuidof(IDataSource),
                        (void**)&pDsrc2);


   /*
   * Save this message to some folder, e.g.
   * Folder/item2.eml"
   *    ** Use the current connection used
   *    ** to bind folder above
   */

   hr = pDsrc2->raw_SaveTo(
         _bstr_t(url) + _bstr_t("item2.eml"),
         (IDispatch*)pConn, //Connection from Folder bind above
         adModeReadWrite,
         adCreateOverwrite,
         (RecordOpenOptionsEnum) NULL,
         NULL,
         NULL
         );


   pConn->Close();
   pConn->Release();
   pDsrc2->Release();
   pDsrc->Release();

   return hr;
}
[VBScript]
    Const adModeRead        = 1
    Const adModeReadWrite   = 3
    Const adCreateOverwrite = 67108864

    Dim iFldr
    Set iFldr = CreateObject("CDO.Folder")
    Dim iDsrc
    Set iDsrc = iFldr
    
    ' Open private root folder:
    ' e.g. URL1 = "file://./backofficestorage/microsoft.com/MBX2/useralias/"
    iDsrc.Open URL1, , adModeReadWrite
    
    Dim Conn
    Set Conn = iDsrc.ActiveConnection
    
    Dim iMsg
    Set iMsg = CreateObject("CDO.Message")
    With iMsg
        .To = "someone@microsoft.com"
        .From = "another@microsoft.com"
        .Subject = "Here is the subject"
        .TextBody = "Here is the text of the message"
    End With
    
    Set iDsrc = iMsg
    
    iDsrc.SaveTo "MySavedItems/item8.eml", _
                Conn, _
                adModeReadWrite, _
                adCreateOverwrite