IDataSource Interface

The IDataSource interface defines methods and properties that you can use to provide access to content in other objects.

Member Summary

Remarks

Name	Type	Description
ActiveConnection	N/A	Not implemented. Reserved for future use.
IsDirty (Read-only)	[Visual Basic,VBScript] Boolean [C++,IDL] VARIANT_BOOL	Specifies whether the local data has been changed since the last data source binding or call to the Save method.
Source (Read-only)	[Visual Basic,VBScript] Object [C++,IDL] IUnknown*	Returns a reference to the currently bound object.
SourceClass (Read-only)	[Visual Basic,VBScript] String [C++,IDL] BSTR	Returns the string identifier of the interface that was used to bind to the current data source object.
SourceURL (Read-only)	N/A	Not implemented. Reserved for future use.

Name	Description
Open	Not implemented. Reserved for future use.
OpenObject	Binds to and opens data from the specified object.
Save	Saves the current data into the currently bound data source.
SaveTo	Not implemented. Reserved for future use.
SaveToContainer	Not implemented. Reserved for future use.
SaveToObject	Binds to and saves data into the specified object.

Objects expose implementations of the IDataSource interface to facilitate easy access to content (data) in other objects. For example, the Message object exposes an implementation of the IDataSource interface, and provides a mechanism to bind to content within other BodyPart, Message, Microsoft® ActiveX® Data Objects (ADO) Stream objects, and objects exposing the IStream interface.

Opening other objects is analogous to using Microsoft Word to open Word .doc files: when you open a word file, the file is bound and the contents are copied into the application in which the file is opened. Subsequent Save commands overwrite the file contents with a local copy of the data. When another file is opened or if the user chooses the Save As command, the application rebinds to the new file and the appropriate data transfer occurs, either to or from the acting application. Save commands now act on the newly bound file. When a user closes the application, local data changes may not have been saved into the currently bound file (that is, the local data has been dirtied since the last bind or save), in which case Word displays a dialog box with the question, "Do you want to save the changes you made to filename?" Changes are lost if they are not saved.

Example

[Visual Basic]

' Reference to Microsoft ActiveX Data Objects 2.5 Library
' Reference to Microsoft CDO for Windows 2000 Library
Function ExtractMessage(iBp As IBodyPart) As Message
    Dim iMsg As New CDO.Message
    Dim iDsrc As IDataSource
    Set iDsrc = iMsg
    iDsrc.OpenObject iBp, "IBodyPart"
    Set ExtractMessage = iMsg
End Function

Sub EmbedMessage(iMsg As CDO.Message, iBp As IBodyPart)
    Dim iDsrc As IDataSource
    Set iDsrc = iMsg
    iDsrc.SaveToObject iBp, "IBodyPart"
End Sub

Function LoadMessageFromFile(Path As String) As Message
    Dim Stm As New Stream
    Stm.Open
    Stm.LoadFromFile Path
    Dim iMsg As New CDO.Message
    Dim iDsrc As IDataSource
    Set iDsrc = iMsg
    iDsrc.OpenObject Stm, "_Stream"
    Set LoadMessageFromFile = iMsg
End Function

Sub SaveMessageToFile(iMsg As CDO.Message, Filepath As String)
    Dim Stm As New Stream
    Stm.Open
    Stm.Type = adTypeText
    Stm.Charset = "US-ASCII"
    
    Dim iDsrc As IDataSource
    Set iDsrc = iMsg
    iDsrc.SaveToObject Stm, "_Stream"
    
    Stm.SaveToFile Filepath, adSaveCreateOverWrite
    
End Sub

[C++,IDL]

void EmbedMessage( IMessagePtr iMsg, IBodyPartPtr iBp)
{
      IDataSourcePtr iDsrc;
      iDsrc = iMsg;

      try 
      {      
            iDsrc->SaveToObject(iBp,_bstr_t("IBodyPart"));
      }
      catch(_com_error error)
      {
            throw error;
      }

}

IMessagePtr ExtractMessage(IBodyPartPtr iBp)
{
      IMessagePtr iMsg(__uuidof(Message));
      IDataSourcePtr iDsrc;
      iDsrc = iMsg;

      try 
      {      
            iDsrc->OpenObject(iBp,_bstr_t("IBodyPart"));
      }
      catch(_com_error error)
      {
            throw error;
      }
      return iMsg;

}

IMessagePtr Load_Message_from_File(_bstr_t path)
{
      /*
      ** This example shows a common use of the ADO Stream
      ** object with CDO, namely, opening a serialized
      ** message from a file on disk and loading it into
      ** a CDO Message object.
      **/

      _StreamPtr  pStm(__uuidof(Stream));
      _variant_t varOptional(DISP_E_PARAMNOTFOUND,VT_ERROR);
      try {
            pStm->raw_Open(
                            varOptional, 
                            adModeUnknown,   
                            adOpenStreamUnspecified,
                            NULL,
                            NULL);
            pStm->LoadFromFile(path);
      }
      catch(_com_error e)
      {
            throw e;
      }

      IMessagePtr iMsg(__uuidof(Message));
      IDataSourcePtr iDsrc;
      iDsrc = iMsg;

      try {
            iDsrc->OpenObject(pStm,_bstr_t("_Stream"));
      }
      catch(_com_error e)
      {
            throw e;
      }
      return iMsg;
}

void Save_Message_to_File(IMessagePtr iMsg, bstr_t filename)
{
      /*
      ** This example shows a common use of the ADO Stream
      ** object with CDO, namely, saving a serialized
      ** message to disk using an ADO Stream object.
      **/
      _StreamPtr  pStm(__uuidof(Stream));
      IDataSourcePtr iDsrc;
      iDsrc = iMsg;

      _variant_t varOptional(DISP_E_PARAMNOTFOUND,VT_ERROR);
      pStm->raw_Open( 
                     varOptional,  
                     adModeUnknown, 
                     adOpenStreamUnspecified,
                     NULL,
                     NULL);
      pStm->Type = adTypeText;
      pStm->Charset = "US-ASCII"; // apparently, we need this!
      try 
      {      
            iDsrc->SaveToObject(pStm,_bstr_t("_Stream"));
      }
      catch(_com_error error)
      {
            throw error;
      }

      try {
            pStm->SaveToFile(filename,adSaveCreateOverWrite);
      }
      catch(_com_error e)
      {
            throw e;
      }
}

[VBScript]

Sub EmbedMessage(iMsg As CDO.Message, iBp As IBodyPart)
    Dim iDsrc
    Set iDsrc = iMsg.DataSource
    iDsrc.SaveToObject iBp, "IBodyPart"
End Sub

Function ExtractMessage(iBp As IBodyPart) As Message
    Dim iMsg
    Set iMsg = CreateObject("CDO.Message")
    Dim iDsrc
    Set iDsrc = iMsg.DataSource
    iDsrc.OpenObject iBp, "IBodyPart"
    Set ExtractMessage = iMsg
End Function

Function LoadMessageFromFile(Path) As Message
    Dim Stm
    Set Stm = CreateObject("ADODB.Stream")
    Stm.Open
    Stm.LoadFromFile Path
    Dim iMsg
    Set iMsg = CreateObject("CDO.Message")
    Dim iDsrc
    Set iDsrc = iMsg
    iDsrc.OpenObject Stm, "_Stream"
    Set LoadMessageFromFile = iMsg
End Function

Sub SaveMessageToFile(iMsg, Filepath)
    Dim Stm
    Set Stm = CreateObject("ADODB.Stream")
    Stm.Open
    Stm.Type = adTypeText ' 2
    Stm.Charset = "US-ASCII"
    
    Dim iDsrc
    Set iDsrc = iMsg.DataSource
    iDsrc.SaveToObject Stm, "_Stream"
    
    Stm.SaveToFile Filepath, adSaveCreateOverWrite
    
End Sub