COleStreamFile Class

Represents a stream of data (IStream) in a compound file as part of OLE Structured Storage.

Syntax

class COleStreamFile : public CFile

Members

Public Constructors

Name	Description
COleStreamFile::COleStreamFile	Constructs a COleStreamFile object.

Public Methods

Name	Description
COleStreamFile::Attach	Associates a stream with the object.
COleStreamFile::CreateMemoryStream	Creates a stream from global memory and associates it with the object.
COleStreamFile::CreateStream	Creates a stream and associates it with the object.
COleStreamFile::Detach	Disassociates the stream from the object.
COleStreamFile::GetStream	Returns the current stream.
COleStreamFile::OpenStream	Safely opens a stream and associates it with the object.

Remarks

An IStorage object must exist before the stream can be opened or created unless it is a memory stream.

COleStreamFile objects are manipulated exactly like CFile objects.

For more information about manipulating streams and storages, see the article Containers: Compound Files..

For more information, see IStream and IStorage in the Windows SDK.

Inheritance Hierarchy

CObject

CFile

COleStreamFile

Requirements

Header: afxole.h

COleStreamFile::Attach

Associates the supplied OLE stream with the COleStreamFile object.

void Attach(LPSTREAM lpStream);

Parameters

lpStream
Points to the OLE stream (IStream) to be associated with the object. Cannot be NULL.

Remarks

The object must not already be associated with an OLE stream.

For more information, see IStream in the Windows SDK.

COleStreamFile::COleStreamFile

Creates a COleStreamFile object.

COleStreamFile(LPSTREAM lpStream = NULL);

Parameters

lpStream
Pointer to the OLE stream to be associated with the object.

Remarks

If lpStream is NULL, the object is not associated with an OLE stream, otherwise, the object is associated with the supplied OLE stream.

For more information, see IStream in the Windows SDK.

COleStreamFile::CreateMemoryStream

Safely creates a new stream out of global, shared memory where a failure is a normal, expected condition.

BOOL CreateMemoryStream(CFileException* pError = NULL);

Parameters

pError
Points to a CFileException object or NULL that indicates the completion status of the create operation. Supply this parameter if you want to monitor possible exceptions generated by attempting to create the stream.

Return Value

Nonzero if the stream is created successfully; otherwise 0.

Remarks

The memory is allocated by the OLE subsystem.

For more information, see CreateStreamOnHGlobal in the Windows SDK.

COleStreamFile::CreateStream

Safely creates a new stream in the supplied storage object where a failure is a normal, expected condition.

BOOL CreateStream(
    LPSTORAGE lpStorage,
    LPCTSTR lpszStreamName,
    DWORD nOpenFlags = modeReadWrite|shareExclusive|modeCreate,
    CFileException* pError = NULL);

Parameters

lpStorage
Points to the OLE storage object that contains the stream to be created. Cannot be NULL.

lpszStreamName
Name of the stream to be created. Cannot be NULL.

nOpenFlags
Access mode to use when opening the stream. Exclusive, read/write, and create modes are used by default. For a complete list of the available modes, see CFile::CFile.

pError
Points to a CFileException object or NULL. Supply this parameter if you want to monitor possible exceptions generated by attempting to create the stream.

Return Value

Nonzero if the stream is created successfully; otherwise 0.

Remarks

A file exception will be thrown if the open fails and pError is not NULL.

For more information, see IStorage::CreateStream in the Windows SDK.

COleStreamFile::Detach

Disassociates the stream from the object without closing the stream.

LPSTREAM Detach();

Return Value

A pointer to the stream (IStream) that was associated with the object.

Remarks

The stream must be closed in some other fashion before the program terminates.

For more information, see IStream in the Windows SDK.

COleStreamFile::GetStream

Call this function to return a pointer to current stream.

IStream* GetStream() const;

Return Value

A pointer to the current stream interface ( IStream).

COleStreamFile::OpenStream

Opens an existing stream.

BOOL OpenStream(
    LPSTORAGE lpStorage,
    LPCTSTR lpszStreamName,
    DWORD nOpenFlags = modeReadWrite|shareExclusive,
    CFileException* pError = NULL);

Parameters

lpStorage
Points to the OLE storage object that contains the stream to be opened. Cannot be NULL.

lpszStreamName
Name of the stream to be opened. Cannot be NULL.

nOpenFlags
Access mode to use when opening the stream. Exclusive and read/write modes are used by default. For the complete list of the available modes, see CFile::CFile.

pError
Points to a CFileException object or NULL. Supply this parameter if you want to monitor possible exceptions generated by attempting to open the stream.

Return Value

Nonzero if the stream is opened successfully; otherwise 0.

Remarks

A file exception will be thrown if the open fails and pError is not NULL.

For more information, see IStorage::OpenStream in the Windows SDK.

See also

CFile Class
Hierarchy Chart