OpenStreamOnFile

The OpenStreamOnFile function allocates and initializes an OLE IStream object to access the contents of a file.

Quick Info

HRESULT STDMETHODCALLTYPE OpenStreamOnFile( 
  LPALLOCATEBUFFER lpAllocateBuffer,   
  LPFREEBUFFER lpFreeBuffer,           
  ULONG ulFlags,                       
  LPTSTR lpszFileName,                 
  LPTSTR lpszPrefix,                   
  LPSTREAM FAR * lppStream             
); 
 

Parameters

lpAllocateBuffer

[in] Pointer to the MAPIAllocateBuffer function, to be used where required by MAPI to allocate memory.

lpFreeBuffer

[in] Pointer to the MAPIFreeBuffer function, to be used where required by MAPI to free memory.

ulFlags

[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:

SOF_UNIQUEFILENAME

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.

STGM_CREATE

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.

STGM_DELETEONRELEASE

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.

STGM_READ

The file is to be created or opened with read-only access.

STGM_READWRITE

The file is to be created or opened with read/write access. If this flag is not set, the STGM_CREATE flag must not be set either.

lpszFileName

[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.

lpszPrefix

[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.

lppStream

[out] Pointer to a pointer to an object exposing the IStream interface.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NO_ACCESS

The file could not be accessed due to insufficient user permissions or because read-only files cannot be modified.

MAPI_E_NOT_FOUND

The designated file does not exist.

Remarks

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 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.

Notes to Callers

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.

See Also

IStorage Functions