OpenStreamOnFileW
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 cadeias de caracteres UNICODE como argumentos, ao contrário da versão ANSI dessa função OpenStreamOnFile e, portanto, permite caracteres arbitrários no nome do arquivo, incluindo o caminho e a extensão do arquivo.
| Info | Valor |
|---|---|
| Exportado por: |
olmapi32.dll |
| Implementado por: |
Outlook |
| Chamado por: |
Aplicativos cliente e provedores de serviços |
HRESULT STDMETHODCALLTYPE OpenStreamOnFileW(
LPALLOCATEBUFFER lpAllocateBuffer,
LPFREEBUFFER lpFreeBuffer,
ULONG ulFlags,
LPWSTR lpszFileName,
LPWSTR 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 nomeado Unicode para o qual OpenStreamOnFileW 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, OpenStreamOnFileW obterá um caminho apropriado do sistema e os sinalizadores STGM_CREATE e STGM_DELETEONRELEASE devem ser definidos.
lpszPrefix
[in] O prefixo do nome de arquivo Unicode no qual OpenStreamOnFileW 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 OpenStreamOnFileW tem dois usos importantes, além de manipular um arquivo com um nome Unicode, diferenciado pela configuração do sinalizador SOF_UNIQUEFILENAME. Quando esse sinalizador não é definido, OpenStreamOnFileW 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 OpenStreamOnFileW cria um arquivo temporário para conter dados de 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.