OpenStreamOnFile

Applies to: Office 2010 | Outlook 2010 | Visual Studio

Allocates and initializes an OLE IStream object to access the contents of a file. This function takes an ANSI string as the file name including the path and the file extension, therefore, use of the Unicode version of this function, OpenStreamOnFileW, is recommended.

Header file:	Mapiutil.h
Implemented by:	MAPI
Called by:	Client applications and service providers

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

Parameters

• lpAllocateBuffer
  [in] Pointer to the MAPIAllocateBuffer function, to be used to allocate memory.

• lpFreeBuffer
  [in] Pointer to the MAPIFreeBuffer function, to be used 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 permission. 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 Value

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

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.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File	Function	Comment
File.cpp	WriteAttachStreamToFile	MFCMAPI uses the OpenStreamOnFile method to open a stream on a file so an attachment can be written out to it.

See Also

Concepts

MFCMAPI as a Code Sample