Classe CInternetFile

Permite o acesso a ficheiros em sistemas remotos que utilizam protocolos de Internet.

Sintaxe

class CInternetFile : public CStdioFile

Membros

Construtores Protegidos

Métodos Públicos

Operadores Públicos

Membros de Dados Protegidos

Observações

Fornece uma classe base para as classes de ficheiros CHttpFile e CGopherFile . Nunca se cria um CInternetFile objeto diretamente. Em vez disso, crie um objeto de uma das suas classes derivadas chamando CGopherConnection::OpenFile ou CHttpConnection::OpenRequest. Também pode criar um CInternetFile objeto chamando CFtpConnection::OpenFile.

As CInternetFile funções membros , LockRange, UnlockRange, e Duplicate não são implementadas para CInternetFileOpen. Se chamar estas funções num CInternetFile objeto, obterá uma CNotSupportedException.

Para saber mais sobre como CInternetFile funciona com as outras aulas de Internet do MFC, consulte o artigo Programação da Internet com WinInet.

Hierarquia de herança

CObject

CFile

CStdioFile

CInternetFile

Requerimentos

Cabeçalho: afxinet.h

FicheiroCristal::Abortar

Fecha o ficheiro associado a este objeto e torna o ficheiro indisponível para leitura ou escrita.

virtual void Abort();

Observações

Se não tiver fechado o ficheiro antes de destruir o objeto, o destruidor fecha-o por si.

Ao lidar com exceções, Abort difere do Close em dois aspetos importantes. Primeiro, a Abort função não lança uma exceção em falhas porque ignora as falhas. Segundo, Abort não AFIRMA se o ficheiro não foi aberto ou foi encerrado anteriormente.

FicheiroCinternet::Ficheiro Cinternet

Esta função membro é chamada quando um CInternetFile objeto é 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 endereço para um ficheiro da Internet.

pstrFileName
Um apontador para uma string contendo o nome do ficheiro.

pConnection
Um ponteiro para um objeto CInternetConnection .

bReadMode
Indica se o ficheiro é apenas de leitura.

hSession
Um nome para uma sessão na Internet.

pstrServer
Um apontador para uma string contendo o nome do servidor.

dwContext
O identificador de contexto para o CInternetFile objeto. Consulte WinInet Basics para mais informações sobre o identificador de contexto.

Observações

Nunca se cria um CInternetFile objeto diretamente. Em vez disso, crie um objeto de uma das suas classes derivadas chamando CGopherConnection::OpenFile ou CHttpConnection::OpenRequest. Também pode criar um CInternetFile objeto chamando CFtpConnection::OpenFile.

FicheiroCinternet::Fechar

Fecha um CInternetFile e liberta quaisquer dos seus recursos.

virtual void Close();

Observações

Se o ficheiro foi aberto para escrita, há uma chamada implícita ao Flush para garantir que todos os dados armazenados em buffer são gravados no host. Deves ligar Close quando terminares de usar um ficheiro.

FicheiroCinternet::Flush

Chame esta função membro para limpar o conteúdo do buffer de escrita.

virtual void Flush();

Observações

Use Flush para garantir que todos os dados na memória foram realmente escritos na máquina de destino e para garantir que a sua transação com a máquina anfitriã foi concluída. Flush só é eficaz em CInternetFile objetos abertos para escrita.

FicheiroCinternet::GetLength

Devolve o tamanho do ficheiro.

virtual ULONGLONG GetLength() const;

FicheiroCinternet::m_hFile

Um handle para o ficheiro associado a este objeto.

HINTERNET m_hFile;

FicheiroCinternet::operator HINTERNET

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

operator HINTERNET() const;

FicheiroCinternet::Read

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

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

Parâmetros

lpBuf
Um apontador para um endereço de memória onde os dados do ficheiro são lidos.

nCount
O número de bytes a escrever.

Valor de retorno

O número de bytes transferidos para o buffer. O valor de retorno pode ser inferior a nCount se o fim do ficheiro foi atingido.

Observações

A função devolve o número de bytes realmente lidos — um número que pode ser inferior a nCount se o ficheiro terminar. Se ocorrer um erro durante a leitura do ficheiro, a função gera um objeto CInternetException que descreve o erro. Note que ler para além do final do ficheiro não é considerado erro e nenhuma exceção será lançada.

Para garantir que todos os dados são recuperados, uma aplicação deve continuar a chamar o CInternetFile::Read método até que o método devolva zero.

CInternetFile::ReadString

Chame esta função membro para ler um fluxo de caracteres até encontrar um carácter de nova linha.

virtual BOOL ReadString(CString& rString);

virtual LPTSTR ReadString(
    LPTSTR pstr,
    UINT nMax);

Parâmetros

pstr
Um apontador para uma cadeia que receberá a linha a ser lida.

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

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

Valor de retorno

Um ponteiro para o buffer contendo dados simples recuperados do objeto CInternetFile . Independentemente do tipo de dado do buffer passado para este método, este não realiza quaisquer manipulações nos dados (por exemplo, conversão para Unicode), pelo que deve mapear os dados devolvidos para a estrutura que espera, como se o void* tipo fosse devolvido.

NULL se o fim do ficheiro fosse alcançado sem ler quaisquer dados; ou, se booleano, FALSE se o fim do ficheiro fosse alcançado sem ler quaisquer dados.

Observações

A função coloca a linha resultante na memória referenciada pelo parâmetro pstr . Deixa de ler caracteres quando atinge o número máximo de caracteres, especificado pelo nMax. O buffer recebe sempre um carácter nulo de terminação.

Se ligar ReadString sem antes chamar o SetReadBufferSize, obterá um buffer de 4096 bytes.

FicheiroCinternet::Seek

Chame esta função membro para reposicionar o ponteiro num ficheiro previamente aberto.

virtual ULONGLONG Seek(
    LONGLONG lOffset,
    UINT nFrom);

Parâmetros

lOffset
Desloca em bytes para mover o ponteiro de leitura/escrita no ficheiro.

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

• CFile::begin Avance o ponteiro do ficheiro com bytes off a partir do início do ficheiro.

• CFile::current Move o ponteiro do ficheiro 1Off bytes da posição atual no ficheiro.

• CFile::end Move o ponteiro do ficheiro lOff bytes do final do ficheiro. LOff deve ser negativo para procurar no ficheiro existente; valores positivos procuram para além do final do ficheiro.

Valor de retorno

O novo desvio de bytes a partir do início do ficheiro se a posição solicitada for legal; caso contrário, o valor fica indefinido e um objeto CInternetException é lançado.

Observações

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

Neste momento, uma chamada a esta função membro só é suportada para dados associados a CHttpFile objetos. Não é suportado para pedidos FTP ou gopher. Se ligar Seek para um destes serviços não suportados, ele devolve-lhe-á ao código de erro Win32 ERROR_INTERNET_INVALID_OPERATION.

Quando um ficheiro é aberto, o ponteiro do ficheiro está no offset 0, o início do ficheiro.

Example

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

FicheiroCinternet::SetReadBufferSize

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

BOOL SetReadBufferSize(UINT nReadSize);

Parâmetros

nReadSize
O tamanho desejado do buffer em bytes.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0. Se a chamada falhar, pode ser chamada a função Win32 GetLastError para determinar a causa do erro.

Observações

As APIs WinInet subjacentes não realizam buffering, por isso escolha um tamanho de buffer que permita à sua aplicação ler dados de forma eficiente, independentemente da quantidade de dados a ler. Se cada chamada para Read normalmente envolver uma grande quantidade de dados (por exemplo, quatro ou mais kilobytes), não deverá precisar de um buffer. No entanto, se ligar Read para obter pequenos blocos de dados, ou se usar ReadString para ler linhas individuais de cada vez, então um buffer de leitura melhora o desempenho da aplicação.

Por defeito, um CInternetFile objeto não fornece qualquer buffering para leitura. Se chamar a esta função membro, deve certificar-se de que o ficheiro foi aberto para acesso de leitura.

Podes aumentar o tamanho do buffer a qualquer momento, mas encolhê-lo não terá efeito. Se chamar ReadString sem ligar SetReadBufferSizeprimeiro, obterá um buffer de 4096 bytes.

FicheiroCinternet::SetWriteBufferSize

Chame esta função membro para definir o tamanho do buffer de escrita temporário usado por um CInternetFileobjeto derivado em .

BOOL SetWriteBufferSize(UINT nWriteSize);

Parâmetros

nWriteSize
O tamanho do buffer em bytes.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0. Se a chamada falhar, pode ser chamada a função Win32 GetLastError para determinar a causa do erro.

Observações

As APIs WinInet subjacentes não realizam buffering, por isso escolha um tamanho de buffer que permita à sua aplicação escrever dados de forma eficiente, independentemente da quantidade de dados a escrever. Se cada chamada para Escrita normalmente envolver uma grande quantidade de dados (por exemplo, quatro ou mais kilobytes de cada vez), não deverá precisar de um buffer. No entanto, se chamar Write para escrever pequenos blocos de dados, um buffer de escrita melhora o desempenho da sua aplicação.

Por defeito, um CInternetFile objeto não fornece qualquer buffering para a escrita. Se chamar esta função membro, deve certificar-se de que o ficheiro foi aberto para acesso de escrita. Pode alterar o tamanho do buffer de escrita a qualquer momento, mas ao fazê-lo há uma chamada implícita ao Flush.

FicheiroCinternet::Escrever

Chame esta função membro para escrever na memória dada lpvBuf, o número especificado de bytes, nCount.

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

Parâmetros

lpBuf
Um ponteiro para o primeiro byte a ser escrito.

nCount
Especifica o número de bytes a escrever.

Observações

Se ocorrer algum erro durante a escrita dos dados, a função gera um objeto CInternetException a descrever o erro.

FicheiroCinternet::WriteString

Esta função escreve uma cadeia terminada por nulo no ficheiro associado.

virtual void WriteString(LPCTSTR pstr);

Parâmetros

pstr
Um apontador para uma cadeia contendo o conteúdo a escrever.

Observações

Se ocorrer algum erro durante a escrita dos dados, a função gera um objeto CInternetException a descrever o erro.

Consulte também

Classe CStdioFile
Gráfico de Hierarquia
Classe CInternetConnection