OpenStreamOnFile

S’applique à : Outlook 2013 | Outlook 2016

Alloue et initialise un objet OLE IStream pour accéder au contenu d’un fichier. Cette fonction prend une chaîne ANSI comme nom de fichier, y compris le chemin d’accès et l’extension de fichier. Par conséquent, l’utilisation de la version Unicode de cette fonction, OpenStreamOnFileW, est recommandée.

Élément	Valeur
Fichier d’en-tête :	Mapiutil.h
Implémenté par :	MAPI
Appelé par :	Applications clientes et fournisseurs de services

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

Paramètres

lpAllocateBuffer

[in] Pointeur vers la fonction MAPIAllocateBuffer , à utiliser pour allouer de la mémoire.

lpFreeBuffer

[in] Pointeur vers la fonction MAPIFreeBuffer , à utiliser pour libérer de la mémoire.

ulFlags

[in] Masque de bits des indicateurs utilisés pour contrôler la création ou l’ouverture du fichier accessible via l’objet OLE IStream . Les indicateurs suivants peuvent être définis :

SOF_UNIQUEFILENAME

Un fichier temporaire doit être créé pour l’objet IStream . Si cet indicateur est défini, les indicateurs STGM_CREATE et STGM_READWRITE doivent également être définis.

STGM_CREATE

Le fichier doit être créé même s’il en existe déjà un. Si le paramètre lpszFileName n’est pas défini, cet indicateur et STGM_DELETEONRELEASE doivent être définis. Si STGM_CREATE est défini, l’indicateur STGM_READWRITE doit également être défini.

STGM_DELETEONRELEASE

Le fichier doit être supprimé lorsque l’objet IStream est libéré. Si le paramètre lpszFileName n’est pas défini, cet indicateur et STGM_CREATE doivent être définis.

STGM_READ

Le fichier doit être créé ou ouvert avec un accès en lecture seule.

STGM_READWRITE

Le fichier doit être créé ou ouvert avec l’autorisation de lecture/écriture. Si cet indicateur n’est pas défini, l’indicateur STGM_CREATE ne doit pas non plus être défini.

lpszFileName

[in] Nom de fichier, y compris le chemin d’accès et l’extension, du fichier pour lequel OpenStreamOnFile initialise l’objet IStream . Si l’indicateur SOF_UNIQUEFILENAME est défini, lpszFileName contient le chemin d’accès au répertoire dans lequel créer un fichier temporaire. Si lpszFileName a la valeur NULL, OpenStreamOnFile obtient un chemin d’accès approprié auprès du système, et les indicateurs STGM_CREATE et STGM_DELETEONRELEASE doivent être définis.

lpszPrefix

[in] Préfixe du nom de fichier sur lequel OpenStreamOnFile initialise l’objet IStream . S’il est défini, le préfixe ne doit pas contenir plus de trois caractères. Si lpszPrefix a la valeur NULL, un préfixe de « SOF » est utilisé.

lppStream

[out] Pointeur vers un pointeur vers un objet exposant l’interface IStream .

Valeur renvoyée

S_OK

L'appel a r�ussi et a renvoy� la valeur attendue ou les valeurs.

MAPI_E_NO_ACCESS

Impossible d’accéder au fichier en raison d’autorisations utilisateur insuffisantes ou parce que les fichiers en lecture seule ne peuvent pas être modifiés.

MAPI_E_NOT_FOUND

Le fichier désigné n’existe pas.

Remarques

La fonction OpenStreamOnFile a deux utilisations importantes, qui se distinguent par la définition de l’indicateur SOF_UNIQUEFILENAME. Lorsque cet indicateur n’est pas défini, OpenStreamOnFile ouvre un objet IStream sur un fichier existant, par exemple pour copier son contenu dans la propriété PR_ATTACH_DATA_BIN (PidTagAttachDataBinary) d’une pièce jointe à l’aide de la méthode IStream ::CopyTo . Dans ce cas, le paramètre lpszFileName spécifie le chemin d’accès et le nom de fichier du fichier.

Lorsque SOF_UNIQUEFILENAME est défini, OpenStreamOnFile crée un fichier temporaire pour contenir les données d’un objet IStream . Pour cette utilisation, le paramètre lpszFileName peut éventuellement désigner le chemin d’accès au répertoire où le fichier doit être créé, et le paramètre lpszPrefix peut éventuellement spécifier un préfixe pour le nom de fichier.

Lorsque l’application cliente appelante ou le fournisseur de services a terminé avec l’objet IStream , il doit le libérer en appelant la méthode OLE IStream ::Release .

MAPI utilise les fonctions pointées par lpAllocateBuffer et lpFreeBuffer pour la plupart des allocations et des désallocations de mémoire, en particulier pour allouer de la mémoire à utiliser par les applications clientes lors de l’appel d’interfaces objet telles que IMAPIProp ::GetProps et IMAPITable ::QueryRows.

Remarques pour les appelants

L’indicateur SOF_UNIQUEFILENAME est utilisé pour créer un fichier temporaire avec un nom unique au système de messagerie. Si cet indicateur est défini, le paramètre lpszFileName spécifie le chemin du fichier temporaire, et le paramètre lpszPrefix contient les caractères de préfixe du nom de fichier. Le nom de fichier construit est <le préfixe>HHHH. TMP, où HHHH est un nombre hexadécimal. Si lpszFileName a la valeur NULL, le fichier est créé dans le répertoire de fichiers temporaire retourné par la fonction Windows GetTempPath, ou dans le répertoire actif si aucun répertoire de fichiers temporaires n’a été désigné.

Si l’indicateur SOF_UNIQUEFILENAME n’est pas défini, lpszPrefix est ignoré et lpszFileName doit contenir le chemin complet et le nom de fichier du fichier à ouvrir ou créer. Le fichier est ouvert ou créé en fonction des autres indicateurs définis dans ulFlags.

Référence MFCMAPI

Pour voir un exemple de code MFCMAPI, consultez le tableau suivant.

Fichier	Fonction	Commentaire
File.cpp	WriteAttachStreamToFile	MFCMAPI utilise la méthode OpenStreamOnFile pour ouvrir un flux sur un fichier afin qu’une pièce jointe puisse y être écrite.

Voir aussi

MFCMAPI comme un exemple de Code