|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here.|
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
Allocates and initializes an OLE IStream object to access the contents of a file.
Client applications and service providers
The OpenStreamOnFile function has two important uses, distinguished by the setting of the SOF_UNIQUEFILENAME flag. When this flag is not set, OpenStreamOnFile opens an IStream object on an existing file, for example to copy its contents to the PR_ATTACH_DATA_BIN (PidTagAttachDataBinary) property of an attachment using the IStream::CopyTo method. In this case the lpszFileName parameter specifies the path and filename of the file.
When SOF_UNIQUEFILENAME is set, OpenStreamOnFile creates a temporary file to hold data for an IStream object. For this usage, the lpszFileName parameter can optionally designate the path to the directory where the file is to be created, and the lpszPrefix parameter can optionally specify a prefix for the filename.
When the calling client application or service provider is finished with the IStream object, it should free it by calling the OLE IStream::Release method.
MAPI uses the functions pointed to by lpAllocateBuffer and lpFreeBuffer for most memory allocation and deallocation, in particular to allocate memory for use by client applications when calling object interfaces such as IMAPIProp::GetProps and IMAPITable::QueryRows.
The SOF_UNIQUEFILENAME flag is used to create a temporary file with a name unique to the messaging system. If this flag is set, the lpszFileName parameter specifes the path for the temporary file, and the lpszPrefix parameter contains the prefix characters of the filename. The constructed filename is <prefix>HHHH.TMP, where HHHH is a hexadecimal number. If lpszFileName is NULL, the file will be created in the temporary file directory that is returned from the Windows function GetTempPath, or the current directory if no temporary file directory has been designated.
If the SOF_UNIQUEFILENAME flag is not set, lpszPrefix is ignored, and lpszFileName should contain the fully qualified path and filename of the file to be opened or created. The file will be opened or created based on the other flags that are set in ulFlags.