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.
[in] Pointer to the MAPIFreeBuffer function, to be used to free memory.
[in] Bitmask of flags used to control the creation or opening of the file to be accessed through the OLE IStream object. The following flags can be set:
A temporary file is to be created for the IStream object. If this flag is set, the STGM_CREATE and STGM_READWRITE flags should also be set.
The file is to be created even if one already exists. If the lpszFileName parameter is not set, both this flag and STGM_DELETEONRELEASE must be set. If STGM_CREATE is set, the STGM_READWRITE flag must also be set.
The file is to be deleted when the IStream object is released. If the lpszFileName parameter is not set, both this flag and STGM_CREATE must be set.
The file is to be created or opened with read-only access.
The file is to be created or opened with read/write permission. If this flag is not set, the STGM_CREATE flag must not be set either.
[in] The filename, including path and extension, of the file for which OpenStreamOnFile initializes the IStream object. If the SOF_UNIQUEFILENAME flag is set, lpszFileName contains the path to the directory in which to create a temporary file. If lpszFileName is NULL, OpenStreamOnFile obtains an appropriate path from the system, and both the STGM_CREATE and STGM_DELETEONRELEASE flags must be set.
[in] The prefix for the filename on which OpenStreamOnFile initializes the IStream object. If set, the prefix must contain not more than three characters. If lpszPrefix is NULL, a prefix of "SOF" is used.
[out] Pointer to a pointer to an object exposing the IStream interface.
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.