IDataSource Interface

Article
10/31/2008

IDataSource Interface

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

IID
CD000029-8B95-11D1-82DB-00C04FB1625D

Extends
IDispatch

Member Summary

Properties

Name	Type	Description
ActiveConnection	N/A	Not implemented. Reserved for future use.
IsDirty (Read-only)	Boolean 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)	Object IUnknown*	Returns a reference to the currently bound object.
SourceClass (Read-only)	String 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.

Methods

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.

Remarks

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.

There are two concepts associated with using the IDataSource interface:

Binding: The OpenObject and SaveToObject methods create an association, or binding between the target object and the binding object. This binding remains active until the object is subsequently rebound or destroyed. While bound, various operations such as the Save method or the IsDirty property act on (or in relation to) the currently bound object.
Directional transfer of data: The OpenObject and SaveToObject methods imply a direction of data flow. For example, the OpenObject method first binds the target object, and then copies the serialized content within the newly bound object into the local object. The SaveToObject method first binds to the target object and then transfers the local object's serialized content into the target object.

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

' 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
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;
      }
}
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

Share via

IDataSource Interface