Classe CInternetFile

Permite o acesso a arquivos em sistemas remotos que usam protocolos de Internet.

Sintaxe

class CInternetFile : public CStdioFile

Membros

Construtores Protegidos

Nome	Descrição
CInternetFile::CInternetFile	Constrói um objeto CInternetFile.

Métodos públicos

Nome	Descrição
CInternetFile::Abort	Fecha o arquivo, ignorando todos os avisos e erros.
CInternetFile::Close	Fecha um CInternetFile e libera seus recursos.
CInternetFile::Flush	Libera o conteúdo do buffer de gravação e garante que os dados na memória sejam gravados no computador de destino.
CInternetFile::GetLength	Retorna o tamanho do arquivo.
CInternetFile::Read	Lê o número de bytes especificados.
CInternetFile::ReadString	Lê um fluxo de caracteres.
CInternetFile::Seek	Reposiciona o ponteiro em um arquivo aberto.
CInternetFile::SetReadBufferSize	Define o tamanho do buffer em que os dados serão lidos.
CInternetFile::SetWriteBufferSize	Define o tamanho do buffer em que os dados serão gravados.
CInternetFile::Write	Grava o número de bytes especificados.
CInternetFile::WriteString	Grava uma cadeia de caracteres terminada em nulo em um arquivo.

Operadores públicos

Nome	Descrição
CInternetFile::operator HINTERNET	Um operador de conversão para um identificador da Internet.

Membros de Dados Protegidos

Nome	Descrição
CInternetFile::m_hFile	Um identificador para um arquivo.

Comentários

Fornece uma classe base para as classes de arquivo CHttpFile e CGopherFile. Você nunca cria um objeto CInternetFile diretamente. Em vez disso, crie um objeto de uma das classes derivadas, chamando CGopherConnection::OpenFile ou CHttpConnection::OpenRequest. Você também pode criar um objeto CInternetFile, chamando CFtpConnection::OpenFile.

As funções de membro CInternetFile, Open, LockRange, UnlockRange e Duplicate não são implementadas para CInternetFile. Se você chamar essas funções em um objeto CInternetFile, obterá um CNotSupportedException.

Para saber mais sobre como CInternetFile funciona com as outras classes de Internet do MFC, confira o artigo Programação na Internet com o WinInet.

Hierarquia de herança

CObject

CFile

CStdioFile

CInternetFile

Requisitos

Cabeçalho: afxinet.h

CInternetFile::Abort

Fecha o arquivo associado a esse objeto e torna o arquivo protegido contra leitura ou gravação.

virtual void Abort();

Comentários

Caso ainda não tenha fechado o arquivo antes de destruir o objeto, o destruidor o fechará para você.

Ao tratar exceções, Abort difere de Close de duas formas importantes. Primeiro, a função Abort não gera uma exceção nas falhas porque as ignora. Segundo, Abort não executará ASSERT, se o arquivo não tiver sido aberto ou se tiver sido fechado anteriormente.

CInternetFile::CInternetFile

Essa função membro é chamada quando um objeto CInternetFile é criado.

CInternetFile(
    HINTERNET hFile,
    LPCTSTR pstrFileName,
    CInternetConnection* pConnection,
    BOOL bReadMode);

CInternetFile(
    HINTERNET hFile,
    HINTERNET hSession,
    LPCTSTR pstrFileName,
    LPCTSTR pstrServer,
    DWORD_PTR dwContext,
    BOOL bReadMode);

Parâmetros

hFile
Um identificador para um arquivo da Internet.

pstrFileName
Um ponteiro para uma cadeia de caracteres que contém o nome do arquivo.

pConnection
Um ponteiro para um objeto CInternetConnection.

bReadMode
Indica se o arquivo é somente leitura.

hSession
Um identificador para uma sessão da Internet.

pstrServer
Um ponteiro para uma cadeia de caracteres contendo o nome do servidor.

dwContext
O identificador de contexto do objeto CInternetFile. Confira Noções Básicas sobre WinInet, para obter mais informações sobre o identificador de contexto.

Comentários

Você nunca cria um objeto CInternetFile diretamente. Em vez disso, crie um objeto de uma das classes derivadas, chamando CGopherConnection::OpenFile ou CHttpConnection::OpenRequest. Você também pode criar um objeto CInternetFile, chamando CFtpConnection::OpenFile.

CInternetFile::Close

Fecha um CInternetFile e libera qualquer um de seus recursos.

virtual void Close();

Comentários

Se o arquivo foi aberto para gravação, há uma chamada implícita para Flush para garantir que todos os dados em buffer sejam gravados no host. Você deve chamar Close, quando terminar de usar um arquivo.

CInternetFile::Flush

Chame essa função de membro para liberar o conteúdo do buffer de gravação.

virtual void Flush();

Comentários

Use Flush para garantir que todos os dados na memória foram realmente gravados no computador de destino e para garantir que a transação com o computador host tenha sido concluída. Flush só é eficaz nos objetos CInternetFile abertos para gravação.

CInternetFile::GetLength

Retorna o tamanho do arquivo.

virtual ULONGLONG GetLength() const;

CInternetFile::m_hFile

Um identificador para o arquivo associado a esse objeto.

HINTERNET m_hFile;

CInternetFile::operator HINTERNET

Use este operador para obter o identificador do Windows para a sessão da Internet atual.

operator HINTERNET() const;

CInternetFile::Read

Chame essa função de membro para ler na memória fornecida, começando em lpvBuf, o número especificado de bytes, nCount.

virtual UINT Read(
    void* lpBuf,
    UINT nCount);

Parâmetros

lpBuf
Um ponteiro para um endereço de memória em que os dados de arquivo são lidos.

nCount
O número de bytes a serem gravados.

Valor de Devolução

O número de bytes transferidos ao buffer. O valor retornado pode ser menor que nCount, se você chegou ao final do arquivo.

Comentários

A função retorna o número de bytes realmente lidos – um número que pode ser menor que nCount, se o arquivo terminar. Se ocorrer um erro ao ler o arquivo, a função gerará um objeto CInternetException que descreve o erro. Observe que a leitura após o final do arquivo não é considerada um erro e nenhuma exceção será gerada.

Para garantir que todos os dados sejam recuperados, um aplicativo deve continuar a chamar o método CInternetFile::Read até que o método retorne zero.

CInternetFile::ReadString

Chame essa função de membro para ler um fluxo de caracteres até encontrar um caractere de nova linha.

virtual BOOL ReadString(CString& rString);

virtual LPTSTR ReadString(
    LPTSTR pstr,
    UINT nMax);

Parâmetros

pstr
Um ponteiro para uma cadeia de caracteres que receberá a linha que está sendo lida.

nMax
O número máximo de caracteres a serem lidos.

rString
Uma referência ao objeto CString que recebe a linha de leitura.

Valor de Devolução

Um ponteiro para o buffer que contém os dados sem formatação recuperados do objeto CInternetFile. Independentemente do tipo de dados do buffer passado para esse método, não são executadas manipulações nos dados (por exemplo, conversão para Unicode). Portanto, você deve mapear os dados retornados para a estrutura esperada, como se o tipo void* tivesse sido retornado.

NULL, se você chegou ao fim do arquivo sem ler os dados. Ou, se booliano, FALSE, se você chegou ao fim do arquivo sem ler os dados.

Comentários

A função coloca a linha resultante na memória referenciada pelo parâmetro pstr. Ela interrompe a leitura de caracteres quando atinge o número máximo de caracteres, especificado por nMax. O buffer sempre recebe um caractere nulo de término.

Se você chamar ReadString sem chamar SetReadBufferSize pela primeira vez, receberá um buffer de 4096 bytes.

CInternetFile::Seek

Chame essa função de membro para reposicionar o ponteiro em um arquivo aberto anteriormente.

virtual ULONGLONG Seek(
    LONGLONG lOffset,
    UINT nFrom);

Parâmetros

lOffset
Deslocamento em bytes para mover o ponteiro de leitura/gravação no arquivo.

nFrom
Referência relativa para o deslocamento. Deve ser um dos seguintes valores:

• CFile::begin Mova o ponteiro de arquivo lOff bytes para a frente desde o início do arquivo.

• CFile::current Mova o ponteiro de arquivo lOff bytes desde a posição atual no arquivo.

• CFile::end Mova o ponteiro de arquivo lOff bytes desde o final do arquivo. lOff deve ser negativo para buscar no arquivo existente. Os valores positivos buscarão além do final do arquivo.

Valor de Devolução

O novo deslocamento de bytes do início do arquivo, se a posição solicitada for legal. Caso contrário, o valor é indefinido e um objeto CInternetException é gerado.

Comentários

A função Seek permite acesso aleatório ao conteúdo de um arquivo movendo o ponteiro em uma quantidade especificada, absolutamente ou relativamente. Nenhum dado é realmente lido durante a busca.

No momento, há suporte para uma chamada para essa função de membro somente para dados associados a objetos CHttpFile. Não há suporte para solicitações FTP ou gopher. Se você chamar Seek para um desses serviços sem suporte, você receberá novamente o código de erro do Win32 ERROR_INTERNET_INVALID_OPERATION.

Quando um arquivo é aberto, o ponteiro do arquivo está no deslocamento 0, desde o início do arquivo.

Observação

O uso de Seek pode fazer com que uma chamada implícita seja liberada.

Exemplo

Confira o exemplo para a implementação da classe base (CFile::Seek).

CInternetFile::SetReadBufferSize

Chame essa função de membro para definir o tamanho do buffer de leitura temporário usado por um objeto derivado de CInternetFile.

BOOL SetReadBufferSize(UINT nReadSize);

Parâmetros

nReadSize
O tamanho do buffer desejado em bytes.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0. Se a chamada falhar, a função Win32 GetLastError poderá ser chamada para determinar a causa do erro.

Comentários

As APIs WinInet subjacentes não executam o buffer. Portanto, escolha um tamanho de buffer que permita que o aplicativo leia os dados com eficiência, independentemente do volume de dados a serem lidos. Se cada chamada para Read normalmente envolve um grande volume de dados (por exemplo, quatro ou mais quilobytes), você não deve precisar de um buffer. No entanto, se você chamar Read para obter pequenas partes de dados ou se usar ReadString para ler linhas individuais de cada vez, um buffer de leitura melhorará o desempenho do aplicativo.

Por padrão, um objeto CInternetFile não fornece buffer para leitura. Se você chamar essa função de membro, deve ter certeza de que o arquivo foi aberto para acesso de leitura.

Você pode aumentar o tamanho do buffer a qualquer momento, mas a redução do buffer não entrará em vigor. Se você chamar ReadString sem chamar SetReadBufferSize primeiro, receberá um buffer de 4096 bytes.

CInternetFile::SetWriteBufferSize

Chame essa função de membro para definir o tamanho do buffer de gravação temporário usado por um objeto derivado de CInternetFile.

BOOL SetWriteBufferSize(UINT nWriteSize);

Parâmetros

nWriteSize
O tamanho do buffer em bytes.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0. Se a chamada falhar, a função Win32 GetLastError poderá ser chamada para determinar a causa do erro.

Comentários

As APIs WinInet subjacentes não executam o buffer. Portanto, escolha um tamanho de buffer que permita que o aplicativo grave os dados com eficiência, independentemente do volume de dados a serem gravados. Se cada chamada para Write normalmente envolve um grande volume de dados (por exemplo, quatro ou mais quilobytes de cada vez), você não deve precisar de um buffer. No entanto, se você chamar Write para gravar pequenas partes de dados, um buffer de gravação melhorará o desempenho do aplicativo.

Por padrão, um objeto CInternetFile não fornece buffer para gravação. Se você chamar essa função de membro, deve ter certeza de que o arquivo foi aberto para acesso de gravação. Você pode alterar o tamanho do buffer de gravação a qualquer momento, mas isso causa uma chamada implícita para Flush.

CInternetFile::Write

Chame essa função de membro para gravar na memória fornecida, lpvBuf, o número especificado de bytes, nCount.

virtual void Write(
    const void* lpBuf,
    UINT nCount);

Parâmetros

lpBuf
Um ponteiro do primeiro byte a ser gravado.

nCount
Especifica o número de bytes a serem gravados.

Comentários

Se ocorrer algum erro ao gravar os dados, a função gerará um objeto CInternetException que descreve o erro.

CInternetFile::WriteString

Essa função grava uma cadeia de caracteres terminada em nulo no arquivo associado.

virtual void WriteString(LPCTSTR pstr);

Parâmetros

pstr
Um ponteiro para uma cadeia de caracteres que contém o conteúdo a ser gravado.

Comentários

Se ocorrer algum erro ao gravar os dados, a função gerará um objeto CInternetException que descreve o erro.

Confira também

Classe CStdioFile
Gráfico da hierarquia
Classe CInternetConnection