OpenStreamOnFile
Aplica-se a: Outlook 2013 | Outlook 2016
Aloca e inicializa um objeto OLE IStream para acessar o conteúdo de um arquivo. Essa função usa uma cadeia de caracteres ANSI como o nome do arquivo, incluindo o caminho e a extensão do arquivo, portanto, o uso da versão Unicode dessa função, OpenStreamOnFileW, é recomendado.
| Item | Valor |
|---|---|
| Arquivo de cabeçalho: |
Mapiutil.h |
| Implementado por: |
MAPI |
| Chamado por: |
Aplicativos cliente e provedores de serviços |
HRESULT STDMETHODCALLTYPE OpenStreamOnFile(
LPALLOCATEBUFFER lpAllocateBuffer,
LPFREEBUFFER lpFreeBuffer,
ULONG ulFlags,
LPSTR lpszFileName,
LPSTR lpszPrefix,
LPSTREAM FAR * lppStream
);
Parâmetros
lpAllocateBuffer
[in] Ponteiro para a função MAPIAllocateBuffer , a ser usada para alocar memória.
lpFreeBuffer
[in] Ponteiro para a função MAPIFreeBuffer , a ser usada para liberar memória.
ulFlags
[in] Bitmask de sinalizadores usados para controlar a criação ou abertura do arquivo a ser acessado por meio do objeto OLE IStream . Os seguintes sinalizadores podem ser definidos:
SOF_UNIQUEFILENAME
Um arquivo temporário deve ser criado para o objeto IStream . Se esse sinalizador estiver definido, os sinalizadores STGM_CREATE e STGM_READWRITE também deverão ser definidos.
STGM_CREATE
O arquivo deve ser criado mesmo que já exista um. Se o parâmetro lpszFileName não estiver definido, esse sinalizador e STGM_DELETEONRELEASE devem ser definidos. Se STGM_CREATE estiver definido, o sinalizador de STGM_READWRITE também deverá ser definido.
STGM_DELETEONRELEASE
O arquivo deve ser excluído quando o objeto IStream for lançado. Se o parâmetro lpszFileName não estiver definido, esse sinalizador e STGM_CREATE devem ser definidos.
STGM_READ
O arquivo deve ser criado ou aberto com acesso somente leitura.
STGM_READWRITE
O arquivo deve ser criado ou aberto com permissão de leitura/gravação. Se esse sinalizador não estiver definido, o sinalizador de STGM_CREATE também não deverá ser definido.
lpszFileName
[in] O nome do arquivo, incluindo caminho e extensão, do arquivo para o qual OpenStreamOnFile inicializa o objeto IStream . Se o sinalizador SOF_UNIQUEFILENAME estiver definido, lpszFileName conterá o caminho para o diretório no qual criar um arquivo temporário. Se lpszFileName for NULL, OpenStreamOnFile obterá um caminho apropriado do sistema e os sinalizadores STGM_CREATE e STGM_DELETEONRELEASE devem ser definidos.
lpszPrefix
[in] O prefixo para o nome de arquivo no qual OpenStreamOnFile inicializa o objeto IStream . Se definido, o prefixo não deve conter mais de três caracteres. Se lpszPrefix for NULL, um prefixo de "SOF" será usado.
lppStream
[out] Ponteiro para um ponteiro para um objeto que expõe a interface IStream .
Valor de retorno
S_OK
A chamada foi bem-sucedida e retornou o valor ou valores esperados.
MAPI_E_NO_ACCESS
O arquivo não pôde ser acessado devido a permissões insuficientes do usuário ou porque os arquivos somente leitura não podem ser modificados.
MAPI_E_NOT_FOUND
O arquivo designado não existe.
Comentários
A função OpenStreamOnFile tem dois usos importantes, diferenciados pela configuração do sinalizador SOF_UNIQUEFILENAME. Quando esse sinalizador não é definido, o OpenStreamOnFile abre um objeto IStream em um arquivo existente, por exemplo, para copiar seu conteúdo para a propriedade PR_ATTACH_DATA_BIN (PidTagAttachDataBinary) de um anexo usando o método IStream::CopyTo . Nesse caso, o parâmetro lpszFileName especifica o caminho e o nome do arquivo.
Quando SOF_UNIQUEFILENAME é definido, o OpenStreamOnFile cria um arquivo temporário para armazenar dados para um objeto IStream . Para esse uso, o parâmetro lpszFileName pode, opcionalmente, designar o caminho para o diretório em que o arquivo deve ser criado e o parâmetro lpszPrefix pode, opcionalmente, especificar um prefixo para o nome do arquivo.
Quando o aplicativo cliente ou provedor de serviços de chamada for concluído com o objeto IStream , ele deverá liberá-lo chamando o método OLE IStream::Release .
O MAPI usa as funções apontadas por lpAllocateBuffer e lpFreeBuffer para a maioria da alocação e alocação de memória, em particular para alocar memória para uso por aplicativos cliente ao chamar interfaces de objeto como IMAPIProp::GetProps e IMAPITable::QueryRows.
Notas para chamadores
O sinalizador SOF_UNIQUEFILENAME é usado para criar um arquivo temporário com um nome exclusivo para o sistema de mensagens. Se esse sinalizador for definido, o parâmetro lpszFileName especifica o caminho para o arquivo temporário e o parâmetro lpszPrefix contém os caracteres de prefixo do nome do arquivo. O nome do arquivo construído é <o prefixo>HHHH. TMP, em que HHHH é um número hexadecimal. Se lpszFileName for NULL, o arquivo será criado no diretório de arquivos temporário que é retornado da função Do Windows GetTempPath ou do diretório atual se nenhum diretório de arquivo temporário tiver sido designado.
Se o sinalizador SOF_UNIQUEFILENAME não estiver definido, o lpszPrefix será ignorado e lpszFileName deverá conter o caminho e o nome de arquivo totalmente qualificados do arquivo a ser aberto ou criado. O arquivo será aberto ou criado com base nos outros sinalizadores que são definidos em ulFlags.
Referência do MFCMAPI
Para ver códigos de exemplo do MFCMAPI, confira a tabela a seguir.
| Arquivo | Função | Comentário |
|---|---|---|
| File.cpp |
WriteAttachStreamToFile |
O MFCMAPI usa o método OpenStreamOnFile para abrir um fluxo em um arquivo para que um anexo possa ser gravado nele. |