This API is used to support OLE structured storage streams containing user specified string data in 3ds Max scene files or other OLE Structured Storage based files. More...

Classes
struct	CustomFileStreamHeader
	stream header consists of WORD version number, a private flag DWORD, and a public flag DWORD More...

class	IUnknownDestructorPolicy
	Helper class for controlling IStorage and IStream deletion. More...

Enumerations
enum	kCustomFileStreamEnum { kPersistentStream = 1 , kSaveNonPersistentStream = 2 , kNoLoadOnSceneLoad = 4 }
	enum values for the private DWORD flag - bits, so powers of 2 More...

enum class	kDeleteStream_result { kOk , kBadArgument , kFileStorageOpenFailed , kCustomDataStorageOpenFailed , kStreamDoesNotExist , kDestroyElementFailed }

enum class	kGetLastCharacterOfContent_result { kOk , kBadArgument , kStreamSeekFailure , kStreamReadFailure , kNoStreamContent }

Functions
DllExport bool	DoesCustomFileStreamStorageExist (const wchar_t *fileName)
	Checks if a file exists and contains a storage called CustomFileStreamDataStorage. More...

DllExport IStorage *	OpenStorageForWrite (const wchar_t fileName, IStorage &pFileIStorage)
	Open a file as an OLE structured storage file with read/write access. More...

DllExport IStorage *	OpenStorageForRead (const wchar_t fileName, IStorage &pFileIStorage)
	Open a file as an OLE structured storage file with read access. More...

DllExport IStream *	OpenStreamForWrite (IStorage pIStorage, const wchar_t streamName, DWORD privateFlags, DWORD publicFlags=0, WORD version=kCustomFileStreamVersion)
	Open a stream with read/write access, creating it if not present. More...

DllExport IStream *	OpenStreamForRead (IStorage pIStorage, const wchar_t streamName)
	Open a stream with read access. More...

DllExport bool	ValidateStream (IStream pIStream, CustomFileStreamHeader stream_header=nullptr)
	Validates that stream was created via CustomFileStream methods, captures private and public flag values if wanted, leaves IStream positioned immediately past header. More...

DllExport unsigned __int64	GetStreamContentByteCount (IStream *pIStream)
	Get the byte count of the content of the stream (the data past the header) More...

DllExport bool	SeekToStartOfStreamContent (IStream *pIStream)
	Sets the stream position to the beginning of the content (the data past the header) More...

DllExport bool	IsStreamContentAnArray (IStream *pIStream)
	Determine if stream content is an array of strings. More...

DllExport bool	ReadStreamContents (IStream *pIStream, std::wstring &content)
	Read the stream contents (the data past the header). More...

DllExport bool	ReadStreamContents (IStream *pIStream, std::vector< std::wstring > &content)
	Read the stream contents (the data past the header) More...

DllExport bool	WriteStreamContents (IStream *pIStream, const std::wstring &content)
	Write the stream contents (the data past the header), erasing any previous content. More...

DllExport bool	WriteStreamContents (IStream *pIStream, const std::vector< std::wstring > &content)
	Write the stream contents (the data past the header), erasing any previous content. More...

DllExport bool	GetStreamNames (IStorage *pIStorage, std::vector< std::wstring > &streamNames)
	Read the CustomFileStream names. More...

DllExport kDeleteStream_result	DeleteFileStream (const wchar_t fileName, const wchar_t streamName)
	Delete the specified CustomFileStream stream from the specified file. More...

DllExport kGetLastCharacterOfContent_result	GetLastCharacterOfContent (IStream *pIStream, wchar_t &theChar)
	Get the last character of content in a stream. More...

Variables
static const WORD	kCustomFileStreamVersion = 1
	the current stream format version number More...

static const wchar_t *	kCustomFileStreamStorageName = L"CustomFileStreamDataStorage"
	the CustomFileStream IStorage name More...

static const int	kMaxStreamNameLength = 31
	OLE limit of 31 chars for stream name. More...

Detailed Description

This API is used to support OLE structured storage streams containing user specified string data in 3ds Max scene files or other OLE Structured Storage based files.

See https://msdn.microsoft.com/en-us/library/windows/desktop/aa380369(v=vs.85).aspx for a description of OLE Structured Storage. Within 3ds Max, this API is used by CustomFileStream.dlu and implemented by CustomFileStreamAPI.dll source. The source for these are in maxsdk\samples\utilities\CustomFileStream. CustomFileStream.dlu defines the CustomSceneStreamManager and CustomFileStream FPS (Function Publishing System) interfaces. CustomFileStreamAPI.dll defines the low level file access methods that are used by CustomFileStream.dlu, and can be used by external applications to read, write, and modify the CustomFileStream as supported by the CustomSceneStreamManager and CustomFileStream interfaces. To use this dll, you would link against CustomFileStreamAPI.lib in maxsdk\libs. There are no dependencies by CustomFileStreamAPI.dll on other 3ds Max dlls. To see how these low level methods should be tied together, see the CustomFileStream.dlu source. This API will read and write CustomFileStream to 3ds Max scene files written by any version of 3ds Max. The CustomSceneStreamManager is required to persist the custom data streams across scene file load and save operations. CustomFileStream as supported by CustomSceneStreamManager and CustomFileStream are located in the CustomFileStream IStorage of the 3ds Max scene file main IStorage. Each stream consists of a header consisting of a 1 WORD version number and two 32 bit DWORD values (see CustomFileStreamHeader below), followed by a non-null terminated wchar string or an array of null terminated wchar strings. The current version number is 1. The first 32 bit DWORD is considered private (flag bit usage defined by Autodesk) and the second is considered public (flag bit usage defined by the creator of the stream). Currently, bits 1 to 3 of the private DWORD are used. Bit 1 signifies that the stream is a persistent stream. When this bit is set, the CustomSceneStreamManager will write this stream to the scene file when the scene file is saved. This allows an CustomFileStream to be automatically persisted across a load/save operation. Bit 2 signifies that the stream is to be saved to the scene file when the scene file is saved, but the stream is not necessarily a persistent stream. This allows the user to add streams to CustomSceneStreamManager's cache and have those streams be written to the scene file. This bit is not persisted to the scene file, and is cleared when read from the scene file. Bit 3 signifies that the stream is not to be added to the CustomSceneStreamManager's cache when the scene file is loaded. If neither of the first 2 bits are set, CustomSceneStreamManager does not write this stream to the scene file when the scene file is saved. The content of the stream is considered to be an array of strings if the last character in the content is a null character (signifying an array of null terminated strings), otherwise the content is considered to be a single non-null terminated string,

Enumeration Type Documentation

◆ kCustomFileStreamEnum

enum kCustomFileStreamEnum

enum values for the private DWORD flag - bits, so powers of 2

Enumerator
kPersistentStream	stream is to be persisted across scene file load/save
kSaveNonPersistentStream	stream is to be written on scene file save
kNoLoadOnSceneLoad	stream is not to be read on scene file load

                                    {
             kPersistentStream = 1,          
             kSaveNonPersistentStream = 2,   
             kNoLoadOnSceneLoad = 4          
         };

◆ kDeleteStream_result

enum kDeleteStream_result

strong

Enumerator
kOk	stream deletion successful
kBadArgument	bad function argument
kFileStorageOpenFailed	failure to open file storage for write
kCustomDataStorageOpenFailed	failure to open custom data storage for write
kStreamDoesNotExist	stream does not exist
kDestroyElementFailed	DestroyElement call on stream failed.

                                         {
             kOk,                            
             kBadArgument,                   
             kFileStorageOpenFailed,         
             kCustomDataStorageOpenFailed,   
             kStreamDoesNotExist,            
             kDestroyElementFailed           
         };

◆ kGetLastCharacterOfContent_result

enum kGetLastCharacterOfContent_result

strong

Enumerator
kOk	call successful
kBadArgument	bad function argument
kStreamSeekFailure	seek failure on stream
kStreamReadFailure	read failure on stream
kNoStreamContent	no content in stream

                                                      {
             kOk,                            
             kBadArgument,                   
             kStreamSeekFailure,             
             kStreamReadFailure,             
             kNoStreamContent                
         };

Function Documentation

◆ DoesCustomFileStreamStorageExist()

DllExport bool MaxSDK::CustomFileStreamAPI::DoesCustomFileStreamStorageExist ( const wchar_t * fileName )

Checks if a file exists and contains a storage called CustomFileStreamDataStorage.

Parameters

fileName The file name.

Returns: true if the file exists and contains a storage called CustomFileStreamDataStorage

◆ OpenStorageForWrite()

DllExport IStorage* MaxSDK::CustomFileStreamAPI::OpenStorageForWrite	(	const wchar_t *	fileName,
		IStorage *&	pFileIStorage
	)

Open a file as an OLE structured storage file with read/write access.

Parameters

fileName	The file name.
pFileIStorage	[out] The IStorage associated with the file. This IStorage needs to be Released at the same time as the returned IStorage is released.

Returns: The CustomFileStream IStorage

◆ OpenStorageForRead()

DllExport IStorage* MaxSDK::CustomFileStreamAPI::OpenStorageForRead	(	const wchar_t *	fileName,
		IStorage *&	pFileIStorage
	)

Open a file as an OLE structured storage file with read access.

Parameters

fileName	The file name.
pFileIStorage	[out] The IStorage associated with the file. This IStorage needs to be Released at the same time as the returned IStorage is released.

Returns: The CustomFileStream IStorage

◆ OpenStreamForWrite()

DllExport IStream* MaxSDK::CustomFileStreamAPI::OpenStreamForWrite	(	IStorage *	pIStorage,
		const wchar_t *	streamName,
		DWORD	privateFlags,
		DWORD	publicFlags = `0`,
		WORD	version = `kCustomFileStreamVersion`
	)

Open a stream with read/write access, creating it if not present.

Parameters

pIStorage	The CustomFileStream IStorage.
streamName	The stream name. The stream name must be less than 32 characters.
privateFlags	The initial private flags value for the stream, if the stream is created.
publicFlags	The initial public flags value for the stream, if the stream is created.
version	The initial version number for the stream, if the stream is created.

Returns: The IStream

Note: After opening the stream, validate the stream using ValidateStream before using other functions in this API.

◆ OpenStreamForRead()

DllExport IStream* MaxSDK::CustomFileStreamAPI::OpenStreamForRead	(	IStorage *	pIStorage,
		const wchar_t *	streamName
	)

Open a stream with read access.

Parameters

pIStorage	The CustomFileStream IStorage.
streamName	The stream name. The stream name must be less than 32 characters.

Returns: The IStream

Note: After opening the stream, validate the stream using ValidateStream before using other functions in this API on the stream.

◆ ValidateStream()

DllExport bool MaxSDK::CustomFileStreamAPI::ValidateStream	(	IStream *	pIStream,
		CustomFileStreamHeader *	stream_header = `nullptr`
	)

Validates that stream was created via CustomFileStream methods, captures private and public flag values if wanted, leaves IStream positioned immediately past header.

Verifies the stream is long enough to contain the stream header data, that the header data was read successfully, and the version number is equal to or less than the current version number. After opening a stream, this function should be used to validate the stream before using other functions in this API on the stream.

Parameters

pIStream	The IStream.
stream_header	[out] If not null, will hold the stream header data that was read from the file.

Returns: true if the stream appears to have been created via CustomFileStream methods.

◆ GetStreamContentByteCount()

DllExport unsigned __int64 MaxSDK::CustomFileStreamAPI::GetStreamContentByteCount ( IStream * pIStream )

Get the byte count of the content of the stream (the data past the header)

Parameters

pIStream The IStream.

Returns: The byte count of the content of the stream (the data past the header).

◆ SeekToStartOfStreamContent()

DllExport bool MaxSDK::CustomFileStreamAPI::SeekToStartOfStreamContent ( IStream * pIStream )

Sets the stream position to the beginning of the content (the data past the header)

Parameters

pIStream The IStream.

Returns: true if successfully positioned.

◆ IsStreamContentAnArray()

DllExport bool MaxSDK::CustomFileStreamAPI::IsStreamContentAnArray ( IStream * pIStream )

Determine if stream content is an array of strings.

Parameters

pIStream The IStream.

Returns: true if stream content is an array of null terminated strings.

◆ ReadStreamContents() [1/2]

DllExport bool MaxSDK::CustomFileStreamAPI::ReadStreamContents	(	IStream *	pIStream,
		std::wstring &	content
	)

Read the stream contents (the data past the header).

If the contents contain an array of strings, the first element of the array is returned.

Parameters

pIStream	The IStream.
content	[out] The content read from the stream.

Returns: true if successfully read.

◆ ReadStreamContents() [2/2]

DllExport bool MaxSDK::CustomFileStreamAPI::ReadStreamContents	(	IStream *	pIStream,
		std::vector< std::wstring > &	content
	)

Read the stream contents (the data past the header)

Parameters

pIStream	The IStream.
content	[out] The content read from the stream.

Returns: true if successfully read.

◆ WriteStreamContents() [1/2]

DllExport bool MaxSDK::CustomFileStreamAPI::WriteStreamContents	(	IStream *	pIStream,
		const std::wstring &	content
	)

Write the stream contents (the data past the header), erasing any previous content.

Parameters

pIStream	The IStream.
content	[out] The content to write to the stream.

Returns: true if successfully written.

◆ WriteStreamContents() [2/2]

DllExport bool MaxSDK::CustomFileStreamAPI::WriteStreamContents	(	IStream *	pIStream,
		const std::vector< std::wstring > &	content
	)

Write the stream contents (the data past the header), erasing any previous content.

Parameters

pIStream	The IStream.
content	The content to write to the stream.

Returns: true if successfully written.

◆ GetStreamNames()

DllExport bool MaxSDK::CustomFileStreamAPI::GetStreamNames	(	IStorage *	pIStorage,
		std::vector< std::wstring > &	streamNames
	)

Read the CustomFileStream names.

Parameters

pIStorage	The CustomFileStream IStorage.
streamNames	[out] The stream names.

Returns: true if successfully read.

◆ DeleteFileStream()

DllExport kDeleteStream_result MaxSDK::CustomFileStreamAPI::DeleteFileStream	(	const wchar_t *	fileName,
		const wchar_t *	streamName
	)

Delete the specified CustomFileStream stream from the specified file.

Only a stream in the CustomFileStream IStorage with the specified name will be deleted.

Parameters

fileName	The file name.
streamName	The stream name. The stream name must be less than 32 characters.

Returns: The success status

◆ GetLastCharacterOfContent()

DllExport kGetLastCharacterOfContent_result MaxSDK::CustomFileStreamAPI::GetLastCharacterOfContent	(	IStream *	pIStream,
		wchar_t &	theChar
	)

Get the last character of content in a stream.

Parameters

pIStream	The IStream.
theChar	[out] The last character of content in the stream.

Returns: The success status

Variable Documentation

◆ kCustomFileStreamVersion

const WORD kCustomFileStreamVersion = 1

static

the current stream format version number

◆ kCustomFileStreamStorageName

const wchar_t* kCustomFileStreamStorageName = L"CustomFileStreamDataStorage"

static

the CustomFileStream IStorage name

◆ kMaxStreamNameLength

const int kMaxStreamNameLength = 31

static

OLE limit of 31 chars for stream name.

Classes

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ kCustomFileStreamEnum

◆ kDeleteStream_result

◆ kGetLastCharacterOfContent_result

Function Documentation

◆ DoesCustomFileStreamStorageExist()

◆ OpenStorageForWrite()

◆ OpenStorageForRead()

◆ OpenStreamForWrite()

◆ OpenStreamForRead()

◆ ValidateStream()

◆ GetStreamContentByteCount()

◆ SeekToStartOfStreamContent()

◆ IsStreamContentAnArray()

◆ ReadStreamContents() [1/2]

◆ ReadStreamContents() [2/2]

◆ WriteStreamContents() [1/2]

◆ WriteStreamContents() [2/2]

◆ GetStreamNames()

◆ DeleteFileStream()

◆ GetLastCharacterOfContent()

Variable Documentation

◆ kCustomFileStreamVersion

◆ kCustomFileStreamStorageName

◆ kMaxStreamNameLength