OpenStreamOnFile
Hace referencia a: Outlook 2013 | Outlook 2016
Asigna e inicializa un objeto OLE IStream para acceder al contenido de un archivo. Esta función toma una cadena ANSI como nombre de archivo, incluida la ruta de acceso y la extensión de archivo, por lo que se recomienda el uso de la versión Unicode de esta función, OpenStreamOnFileW.
| Elemento | Valor |
|---|---|
| Archivo de encabezado: |
Mapiutil.h |
| Implementado por: |
MAPI |
| Llamado por: |
Aplicaciones cliente y proveedores de servicios |
HRESULT STDMETHODCALLTYPE OpenStreamOnFile(
LPALLOCATEBUFFER lpAllocateBuffer,
LPFREEBUFFER lpFreeBuffer,
ULONG ulFlags,
LPSTR lpszFileName,
LPSTR lpszPrefix,
LPSTREAM FAR * lppStream
);
Parameters
lpAllocateBuffer
[in] Puntero a la función MAPIAllocateBuffer , que se usará para asignar memoria.
lpFreeBuffer
[in] Puntero a la función MAPIFreeBuffer , que se usará para liberar memoria.
ulFlags
[in] Máscara de bits de marcas usadas para controlar la creación o apertura del archivo al que se va a acceder a través del objeto OLE IStream . Se pueden establecer las siguientes marcas:
SOF_UNIQUEFILENAME
Se va a crear un archivo temporal para el objeto IStream . Si se establece esta marca, también se deben establecer las marcas de STGM_CREATE y STGM_READWRITE.
STGM_CREATE
El archivo se va a crear incluso si ya existe uno. Si no se establece el parámetro lpszFileName , se deben establecer esta marca y STGM_DELETEONRELEASE. Si se establece STGM_CREATE, también se debe establecer la marca de STGM_READWRITE.
STGM_DELETEONRELEASE
El archivo se eliminará cuando se libere el objeto IStream . Si no se establece el parámetro lpszFileName , se deben establecer esta marca y STGM_CREATE.
STGM_READ
El archivo se va a crear o abrir con acceso de solo lectura.
STGM_READWRITE
El archivo se va a crear o abrir con permiso de lectura y escritura. Si no se establece esta marca, tampoco se debe establecer la marca de STGM_CREATE.
lpszFileName
[in] Nombre de archivo, incluida la ruta de acceso y la extensión, del archivo para el que OpenStreamOnFile inicializa el objeto IStream . Si se establece la marca de SOF_UNIQUEFILENAME, lpszFileName contiene la ruta de acceso al directorio en el que se va a crear un archivo temporal. Si lpszFileName es NULL, OpenStreamOnFile obtiene una ruta de acceso adecuada del sistema y se deben establecer las marcas STGM_CREATE y STGM_DELETEONRELEASE.
lpszPrefix
[in] Prefijo del nombre de archivo en el que OpenStreamOnFile inicializa el objeto IStream . Si se establece, el prefijo no debe contener más de tres caracteres. Si lpszPrefix es NULL, se usa un prefijo "SOF".
lppStream
[out] Puntero a un puntero a un objeto que expone la interfaz IStream .
Valor devuelto
S_OK
La llamada se ha realizado correctamente y devuelva el valor esperado o los valores.
MAPI_E_NO_ACCESS
No se pudo acceder al archivo debido a permisos de usuario insuficientes o porque no se pueden modificar los archivos de solo lectura.
MAPI_E_NOT_FOUND
El archivo designado no existe.
Comentarios
La función OpenStreamOnFile tiene dos usos importantes, que se distinguen por la configuración de la marca de SOF_UNIQUEFILENAME. Cuando no se establece esta marca, OpenStreamOnFile abre un objeto IStream en un archivo existente, por ejemplo, para copiar su contenido en la propiedad PR_ATTACH_DATA_BIN (PidTagAttachDataBinary) de un archivo adjunto mediante el método IStream::CopyTo . En este caso, el parámetro lpszFileName especifica la ruta de acceso y el nombre de archivo del archivo.
Cuando se establece SOF_UNIQUEFILENAME, OpenStreamOnFile crea un archivo temporal para contener datos para un objeto IStream . Para este uso, el parámetro lpszFileName puede designar opcionalmente la ruta de acceso al directorio donde se va a crear el archivo y el parámetro lpszPrefix puede especificar opcionalmente un prefijo para el nombre de archivo.
Cuando la aplicación cliente o el proveedor de servicios que realiza la llamada finalizan con el objeto IStream , debe liberarlo llamando al método OLE IStream::Release .
MAPI usa las funciones a las que apuntan lpAllocateBuffer y lpFreeBuffer para la mayoría de la asignación y desasignación de memoria, en particular para asignar memoria para su uso por las aplicaciones cliente al llamar a interfaces de objeto como IMAPIProp::GetProps e IMAPITable::QueryRows.
Notas para los llamadores
La marca de SOF_UNIQUEFILENAME se usa para crear un archivo temporal con un nombre único para el sistema de mensajería. Si se establece esta marca, el parámetro lpszFileName especifica la ruta de acceso del archivo temporal y el parámetro lpszPrefix contiene los caracteres de prefijo del nombre de archivo. El nombre de archivo construido es <el prefijo>HHHH. TMP, donde HHHH es un número hexadecimal. Si lpszFileName es NULL, el archivo se creará en el directorio de archivos temporales que se devuelve desde la función de Windows GetTempPath o en el directorio actual si no se ha designado ningún directorio de archivo temporal.
Si no se establece la marca de SOF_UNIQUEFILENAME, lpszPrefix se omite y lpszFileName debe contener la ruta de acceso completa y el nombre de archivo del archivo que se va a abrir o crear. El archivo se abrirá o creará en función de las otras marcas establecidas en ulFlags.
Referencia de MFCMAPI
Para obtener un ejemplo de código de MFCMAPI, vea la siguiente tabla.
| Archivo | Función | Comment |
|---|---|---|
| File.cpp |
WriteAttachStreamToFile |
MFCMAPI usa el método OpenStreamOnFile para abrir una secuencia en un archivo para que se pueda escribir un archivo adjunto en él. |