CInternetSession Classe

Cria e inicializa uma ou várias sessões simultâneas de Internet e, se necessário, descreve a sua ligação a um servidor proxy.

Sintaxe

class CInternetSession : public CObject

Membros

Construtores Públicos

Métodos Públicos

Operadores Públicos

Observações

Se a sua ligação à Internet tiver de ser mantida durante toda a aplicação, pode criar um CInternetSession membro da classe CWinApp.

Depois de estabelecer uma sessão na Internet, pode ligar.OpenURL CInternetSession depois analisa a URL para você chamando a função AfxParseURLglobal . Independentemente do tipo de protocolo, CInternetSession interpreta o URL e gere-o por si. Pode lidar com pedidos para ficheiros locais identificados com o recurso URL "file://". OpenURL Devolve um ponteiro para um CStdioFile objeto se o nome que lhe passa for um ficheiro local.

Se abrir uma URL num servidor de Internet usando OpenURL, pode ler informação do site. Se quiser realizar ações específicas de um serviço (por exemplo, HTTP, FTP ou gopher) em ficheiros localizados num servidor, deve estabelecer a ligação apropriada com esse servidor. Para abrir um tipo particular de ligação diretamente a um determinado serviço, utilize uma das seguintes funções membro:

• GetGopherConnection para abrir uma ligação a um serviço de gopher.

• GetHttpConnection para abrir uma ligação a um serviço HTTP.

• GetFtpConnection para abrir uma ligação a um serviço FTP.

SetOption Permite-lhe definir as opções de consulta da sua sessão, como valores de time-out, número de tentativas, e assim por diante.

CInternetSession funções SetCookiemembros , GetCookie, e GetCookieLength fornecem os meios para gerir uma base de dados de cookies Win32, através da qual servidores e scripts mantêm informação de estado sobre a estação de trabalho cliente.

Para mais informações sobre tarefas básicas de programação da Internet, consulte o artigo Internet First Steps: WinInet. Para informações gerais sobre a utilização das classes MFC WinInet , consulte o artigo Programação da Internet com WinInet.

Hierarquia de herança

CObject
 CInternetSession

Requerimentos

Cabeçalho:afxinet.h

CInternetSession::CInternetSession

Esta função membro é chamada quando um CInternetSession objeto é criado.

CInternetSession(
    LPCTSTR pstrAgent = NULL,
    DWORD_PTR dwContext = 1,
    DWORD dwAccessType = PRE_CONFIG_INTERNET_ACCESS,
    LPCTSTR pstrProxyName = NULL,
    LPCTSTR pstrProxyBypass = NULL,
    DWORD dwFlags = 0);

Parâmetros

pstrAgent
Um apontador para uma cadeia que identifica o nome da aplicação ou entidade que chama as funções da Internet (por exemplo, "Microsoft Internet Browser"). Se pstrAgent for NULL (o padrão), o framework chama a função AfxGetAppNameglobal , que devolve uma cadeia terminada por nulo contendo o nome de uma aplicação. Alguns protocolos usam esta cadeia para identificar a sua aplicação no servidor.

dwContext
O identificador de contexto da operação. dwContext identifica a informação de estado da operação devolvida por CInternetSession::OnStatusCallback. O padrão é definido para 1; no entanto, pode atribuir explicitamente um ID de contexto específico para a operação. O objeto e qualquer trabalho que ele faça estarão associados a esse ID de contexto.

dwAccessType
O tipo de acesso necessário. Os seguintes são valores válidos, dos quais exatamente um pode ser fornecido:

• INTERNET_OPEN_TYPE_PRECONFIG Liga-te usando as definições pré-configuradas no registo. Este tipo de acesso está definido como predefinido. Para ligar através de um proxy TIS, defina dwAccessType este valor; depois define o registo de forma adequada.

• INTERNET_OPEN_TYPE_DIRECT Liga-te diretamente à Internet.

• INTERNET_OPEN_TYPE_PROXY Liga-te através de um proxy do CERN.

Para informações sobre como se ligar a diferentes tipos de proxies, veja Passos numa Aplicação Cliente FTP Típica.

pstrProxyName
O nome do proxy preferido do CERN se dwAccessType for definido como INTERNET_OPEN_TYPE_PROXY. A predefinição é NULL.

pstrProxyBypass
Um ponteiro para uma string contendo uma lista opcional de endereços de servidor. Estes endereços podem ser contornados ao utilizar acesso por proxy. Se for fornecido um NULL valor, a lista de bypass será lida do registo. Este parâmetro só tem significado se dwAccessType for definido como INTERNET_OPEN_TYPE_PROXY.

dwFlags
Indica várias opções de cache. O padrão está definido para 0. Os valores possíveis incluem:

• INTERNET_FLAG_DONT_CACHE Não guardes os dados em cache, nem localmente nem em servidores gateway.

• INTERNET_FLAG_OFFLINE As operações de download são feitas apenas através da cache persistente. Se o item não existir na cache, é devolvido um código de erro apropriado. Esta flag pode ser combinada com o operador bit a bit "ou" (|).

Observações

CInternetSession é a primeira função da Internet chamada por uma aplicação. Inicializa as estruturas de dados internas e prepara para futuras chamadas da aplicação.

Se não for possível abrir ligação à Internet, CInternetSession lança um AfxThrowInternetExceptionarquivo .

Example

Veja o exemplo para CFtpFileFind.

CInternetSession::Close

Chame esta função membro quando a sua aplicação terminar de usar o CInternetSession objeto.

virtual void Close();

Example

Veja o exemplo para CFtpFileFind.

CInternetSession::EnableStatusCallback

Chame esta função de membro para ativar o callback de estado.

BOOL EnableStatusCallback(BOOL bEnable = TRUE);

Parâmetros

bEnable
Especifica se o callback está ativado ou desativado. A predefinição é TRUE.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0. Se a chamada falhar, determine a causa da falha examinando o objeto lançado CInternetException .

Observações

Ao gerir o callback de estado, pode fornecer o estado sobre o progresso da operação (como resolver o nome, ligar-se ao servidor, etc.) na barra de estado da aplicação. Exibir o estado operacional é especialmente desejável durante uma operação de longa duração.

Como os callbacks ocorrem durante o processamento do pedido, a aplicação deve passar o mínimo de tempo possível na callback para evitar a degradação do débito de dados para a rede. Por exemplo, colocar uma caixa de diálogo num callback pode ser uma operação tão longa que o servidor termina o pedido.

O callback de estado não pode ser removido enquanto houver chamadas pendentes.

Para gerir qualquer operação de forma assíncrona, deve criar o seu próprio thread ou usar as funções WinInet sem MFC.

CInternetSession::GetContext

Chame esta função membro para obter o valor de contexto para uma sessão de aplicação específica.

DWORD_PTR GetContext() const;

Valor de retorno

O Identificador de contexto definido pela aplicação.

Observações

OnStatusCallback usa o ID de contexto devolvido por GetContext para reportar o estado de uma determinada aplicação. Por exemplo, quando um utilizador ativa um pedido de Internet que envolve a devolução de informações de estado, o callback de estado usa o ID de contexto para reportar o estado desse pedido em particular. Se o utilizador ativar dois pedidos de Internet separados que envolvem ambos a devolução de informação de estado, OnStatusCallback usa os identificadores de contexto para devolver o estado dos pedidos correspondentes. Consequentemente, o identificador de contexto é usado para todas as operações de callback de estado e está associado à sessão até ao fim da sessão.

Para mais informações sobre operações assíncronas, consulte o artigo Internet First Steps: WinInet.

CInternetSession::GetCookie

Esta função membro implementa o comportamento da função InternetGetCookieWin32 , conforme descrito no SDK do Windows.

static BOOL GetCookie(
    LPCTSTR pstrUrl,
    LPCTSTR pstrCookieName,
    LPTSTR pstrCookieData,
    DWORD dwBufLen);

static BOOL GetCookie(
    LPCTSTR pstrUrl,
    LPCTSTR pstrCookieName,
    CString& strCookieData);

Parâmetros

pstrUrl
Um ponteiro para uma string contendo a URL.

pstrCookieName
Um ponteiro para uma string contendo o nome do cookie a obter para a URL especificada.

pstrCookieData
Na primeira sobrecarga, um apontador para uma string contendo o endereço do buffer que recebe os dados dos cookies. Este valor pode ser NULL. Na segunda sobrecarga, uma referência a um CString objeto para receber os dados das cookies.

dwBufLen
A variável que especifica o tamanho do pstrCookieData buffer. Se a função tiver sucesso, o buffer recebe a quantidade de dados copiados para o pstrCookieData buffer. Se pstrCookieData for NULL, este parâmetro recebe um valor que especifica o tamanho do buffer necessário para copiar todos os dados de cookies.

Valor de retorno

Retorna TRUE se for bem-sucedido, ou FALSE não. Se a chamada falhar, chame a função GetLastError Win32 para determinar a causa do erro. Aplicam-se os seguintes valores de erro:

• ERROR_NO_MORE_ITEMS Não existe cookie para o URL especificado e para todos os seus pais.

• ERROR_INSUFFICIENT_BUFFER O valor transmitido dwBufLen é insuficiente para copiar todos os dados dos cookies. O valor devolvido dwBufLen é o tamanho do buffer necessário para obter todos os dados.

Observações

Na segunda sobrecarga, o MFC recupera os dados de cookies para o objeto fornecido.CString

CInternetSession::GetCookieLength

Chame esta função membro para obter o comprimento do cookie armazenado no buffer.

static DWORD GetCookieLength(
    LPCTSTR pstrUrl,
    LPCTSTR pstrCookieName);

Parâmetros

pstrUrl
Um ponteiro para uma cadeia que contém o URL

pstrCookieName
Um apontador para uma cadeia que contém o nome do biscoito.

Valor de retorno

Um DWORD valor que indica o comprimento do cookie, armazenado no buffer. Zero se não existir nenhum cookie com o nome indicado por pstrCookieName .

Observações

Este valor é usado por GetCookie.

CInternetSession::GetFtpConnection

Chame esta função membro para estabelecer uma ligação FTP e obter um ponteiro para um CFtpConnection objeto.

CFtpConnection* GetFtpConnection(
    LPCTSTR pstrServer,
    LPCTSTR pstrUserName = NULL,
    LPCTSTR pstrPassword = NULL,
    INTERNET_PORT nPort = INTERNET_INVALID_PORT_NUMBER,
    BOOL bPassive = FALSE);

Parâmetros

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

pstrUserName
Apontador para uma cadeia terminada por null que especifica o nome do utilizador a iniciar sessão. Se NULL, o padrão é anónimo.

pstrPassword
Um ponteiro para uma cadeia terminada por null que especifica a palavra-passe a usar para iniciar sessão. Se ambos pstrPassword e pstrUserName forem NULL, a palavra-passe anónima padrão é o nome de email do utilizador. Se pstrPassword for NULL (ou uma cadeia vazia) mas pstrUserName não NULLfor , usa-se uma palavra-passe em branco. A tabela seguinte descreve o comportamento para as quatro configurações possíveis de pstrUserName e pstrPassword:

nPort
Um número que identifica a porta TCP/IP a usar no servidor.

bPassive
Especifica modo passivo ou ativo para esta sessão FTP. Se definido para TRUE, define a API dwFlag Win32 para INTERNET_FLAG_PASSIVE.

Valor de retorno

Um ponteiro para um CFtpConnection objeto. Se a chamada falhar, determine a causa da falha examinando o objeto lançado CInternetException .

Observações

GetFtpConnection liga-se a um servidor FTP e cria e devolve um ponteiro para um CFTPConnection objeto. Não realiza nenhuma operação específica no servidor. Se pretende ler ou escrever em ficheiros, por exemplo, deve realizar essas operações como etapas separadas. Consulte as aulas CFtpConnection e CFtpFileFind para informações sobre pesquisa de ficheiros, abertura de ficheiros e leitura ou escrita em ficheiros. Consulte o artigo Programação na Internet com WinInet para passos na execução de tarefas comuns de ligação FTP.

Example

Veja o exemplo para CFtpFileFind.

CInternetSession::GetGopherConnection

Chama esta função membro para estabelecer uma nova ligação gopher e obter um ponteiro para um CGopherConnection objeto.

CGopherConnection* GetGopherConnection(
    LPCTSTR pstrServer,
    LPCTSTR pstrUserName = NULL,
    LPCTSTR pstrPassword = NULL,
    INTERNET_PORT nPort = INTERNET_INVALID_PORT_NUMBER);

Parâmetros

pstrServer
Um apontador para uma string que contém o nome do servidor gopher.

pstrUserName
Um apontador para uma string contendo o nome de utilizador.

pstrPassword
Um apontador para uma string contendo a palavra-passe de acesso.

nPort
Um número que identifica a porta TCP/IP a usar no servidor.

Valor de retorno

Um ponteiro para um CGopherConnection objeto. Se a chamada falhar, determine a causa da falha examinando o objeto lançado CInternetException .

Observações

GetGopherConnection liga-se a um servidor gopher e cria e devolve um ponteiro para um CGopherConnection objeto. Não realiza nenhuma operação específica no servidor. Se pretende ler ou escrever dados, por exemplo, deve realizar essas operações como etapas separadas. Consulte as classes CGopherConnection, CGopherFile, e CGopherFileFind para informações sobre pesquisa de ficheiros, abertura de ficheiros e leitura ou escrita em ficheiros. Para informações sobre como navegar num site FTP, consulte a função OpenURLde membro . Consulte o artigo Programação na Internet com WinInet para passos na execução de tarefas comuns de ligação a gopher.

CInternetSession::GetHttpConnection

Chame esta função membro para estabelecer uma ligação HTTP e obter um ponteiro para um CHttpConnection objeto.

CHttpConnection* GetHttpConnection(
    LPCTSTR pstrServer,
    INTERNET_PORT nPort = INTERNET_INVALID_PORT_NUMBER,
    LPCTSTR pstrUserName = NULL,
    LPCTSTR pstrPassword = NULL);

CHttpConnection* GetHttpConnection(
    LPCTSTR pstrServer,
    DWORD dwFlags,
    INTERNET_PORT nPort = INTERNET_INVALID_PORT_NUMBER,
    LPCTSTR pstrUserName = NULL,
    LPCTSTR pstrPassword = NULL);

Parâmetros

pstrServer
Um apontador para uma string que contém o nome do servidor HTTP.

nPort
Um número que identifica a porta TCP/IP a usar no servidor.

pstrUserName
Um apontador para uma string contendo o nome de utilizador.

pstrPassword
Um apontador para uma string contendo a palavra-passe de acesso.

dwflags
Qualquer combinação das INTERNET_FLAG_* bandeiras. Consulte a tabela na secção Observações de CHttpConnection::OpenRequest para uma descrição dos dwFlags valores.

Valor de retorno

Um ponteiro para um CHttpConnection objeto. Se a chamada falhar, determine a causa da falha examinando o objeto lançado CInternetException .

Observações

GetHttpConnection liga-se a um servidor HTTP e cria e devolve um ponteiro para um CHttpConnection objeto. Não realiza nenhuma operação específica no servidor. Se pretende consultar um cabeçalho HTTP, por exemplo, deve realizar esta operação como um passo separado. Consulte as classes CHttpConnection e CHttpFile para informações sobre operações que pode realizar usando uma ligação a um servidor HTTP. Para informações sobre como navegar num site HTTP, consulte a função OpenURLmembro . Consulte o artigo Programação da Internet com WinInet para os passos na execução de tarefas comuns de ligação HTTP.

CInternetSession::OnStatusCallback

Esta função membro é chamada pelo framework para atualizar o estado quando o callback de estado está ativado e uma operação está pendente.

virtual void OnStatusCallback(
    DWORD_PTR dwContext,
    DWORD dwInternetStatus,
    LPVOID lpvStatusInformation,
    DWORD dwStatusInformationLength);

Parâmetros

dwContext
O valor de contexto fornecido pela aplicação.

dwInternetStatus
Um código de estado que indica porque está a ser feita a chamada de retorno. Consulte Observações para uma tabela dos valores possíveis.

lpvStatusInformation
Um ponteiro para um buffer contendo informação pertinente a este callback.

dwStatusInformationLength
O tamanho de lpvStatusInformation.

Observações

Deve primeiro ligar EnableStatusCallback para aproveitar o estado de retorno.

O dwInternetStatus parâmetro indica a operação a ser realizada e determina qual será o conteúdo de lpvStatusInformation . dwStatusInformationLength indica o comprimento dos dados incluídos em lpvStatusInformation. Os seguintes valores de estado para dwInternetStatus são definidos da seguinte forma:

Substitua esta função de membro para exigir alguma ação antes de ser realizada uma rotina de callback de estado.

AFX_MANAGE_STATE(AfxGetAppModuleState());

Para mais informações sobre operações assíncronas, consulte o artigo Internet First Steps: WinInet.

CInternetSession::OpenURL

Chame esta função membro para enviar o pedido especificado ao servidor HTTP e permitir que o cliente especifique cabeçalhos RFC822, MIME ou HTTP adicionais para enviar juntamente com o pedido.

CStdioFile* OpenURL(
    LPCTSTR pstrURL,
    DWORD_PTR dwContext = 1,
    DWORD dwFlags = INTERNET_FLAG_TRANSFER_ASCII,
    LPCTSTR pstrHeaders = NULL,
    DWORD dwHeadersLength = 0);

Parâmetros

pstrURL
Um ponteiro para o nome da URL para começar a ler. Apenas URLs que começam por file:, ftp:, , gopher:ou http: são suportadas. Afirma se pstrURL for NULL.

dwContext
Um valor definido pela aplicação passado com o handle retornado em callback.

dwFlags
As bandeiras que descrevem como lidar com esta ligação. Consulte Observações para mais informações sobre as bandeiras válidas. As bandeiras válidas são:

• INTERNET_FLAG_TRANSFER_ASCII O padrão. Transfira o ficheiro como texto ASCII.

• INTERNET_FLAG_TRANSFER_BINARY Transfira o ficheiro como um ficheiro binário.

• INTERNET_FLAG_RELOAD Obtém os dados do fio mesmo que estejam em cache local.

• INTERNET_FLAG_DONT_CACHE Não armazene os dados em cache, nem localmente nem em gateways.

• INTERNET_FLAG_SECURE Esta flag aplica-se apenas a pedidos HTTP. Solicita transações seguras na transferência com Secure Sockets Layer ou PCT.

• INTERNET_OPEN_FLAG_USE_EXISTING_CONNECT Se possível, reutilize as ligações existentes ao servidor para novos pedidos gerados em OpenUrl vez de criar uma nova sessão para cada pedido de ligação.

• INTERNET_FLAG_PASSIVE Usado para um site FTP. Usa semântica FTP passiva. Usado com CInternetConnection de OpenURL.

pstrHeaders
Um ponteiro para uma string contendo os cabeçalhos a serem enviados para o servidor HTTP.

dwHeadersLength
O comprimento, em caracteres, dos cabeçalhos adicionais. Se isto for -1L e pstrHeaders for não-NULL, então pstrHeaders assume-se que é terminado a zero e o comprimento é calculado.

Valor de retorno

Devolve um handle de ficheiro apenas para serviços de Internet do tipo FTP, GOPHER, HTTP e FILE. Retorna NULL se a análise não for bem-sucedida.

O ponteiro que OpenURL retorna depende do pstrURLtipo de serviço de . A tabela abaixo ilustra os possíveis ponteiros OpenURL que podem regressar.

Observações

O parâmetro dwFlags deve incluir ou INTERNET_FLAG_TRANSFER_ASCII ou INTERNET_FLAG_TRANSFER_BINARY, mas não ambos. As restantes flags podem ser combinadas com o operador bit a bit "ou" (|).

OpenURL, que envolve a função InternetOpenURLWin32 , permite apenas descarregar, recuperar e ler os dados de um servidor de Internet. OpenURL Não permite manipulação de ficheiros numa localização remota, por isso não requer objeto CInternetConnection .

Para usar funções específicas de ligação (ou seja, específicas de protocolo), como escrever num ficheiro, deve abrir uma sessão, depois abrir um tipo particular de ligação e, em seguida, usar essa ligação para abrir um ficheiro no modo desejado. Consulte CInternetConnection para mais informações sobre funções específicas da ligação.

CInternetSession::operator HINTERNET

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

operator HINTERNET() const;

CInternetSession::SetCookie

Define um cookie para a URL especificada.

static BOOL SetCookie(
    LPCTSTR pstrUrl,
    LPCTSTR pstrCookieName,
    LPCTSTR pstrCookieData);

Parâmetros

pstrUrl
Um ponteiro para uma cadeia terminada em null que especifica a URL para a qual o cookie deve ser definido.

pstrCookieName
Um apontador para uma cadeia que contém o nome do biscoito.

pstrCookieData
Um ponteiro para uma string contendo os dados reais da string para associar à URL.

Valor de retorno

Retorna TRUE se for bem-sucedido, ou FALSE não. Para obter o código de erro específico, ligue GetLastErrorpara .

Observações

Esta função membro implementa o comportamento da mensagem InternetSetCookieWin32 , conforme descrito no SDK do Windows.

CInternetSession::SetOption

Chame esta função membro para definir opções para a sessão na Internet.

BOOL SetOption(
    DWORD dwOption,
    LPVOID lpBuffer,
    DWORD dwBufferLength,
    DWORD dwFlags = 0);

BOOL SetOption(
    DWORD dwOption,
    DWORD dwValue,
    DWORD dwFlags = 0);

Parâmetros

dwOption
A opção de Internet para configurar. Consulte as Flags de Opção no SDK do Windows para uma lista das opções possíveis.

lpBuffer
Um buffer que contém a opção de definição.

dwBufferLength
O comprimento de lpBuffer ou o tamanho de dwValue.

dwValue
A DWORD que contém a opção de definição.

dwFlags
Indica várias opções de cache. O padrão está definido para 0. Os valores possíveis incluem:

• INTERNET_FLAG_DONT_CACHE Não guardes os dados em cache, nem localmente nem em servidores gateway.

• INTERNET_FLAG_OFFLINE As operações de download são feitas apenas através da cache persistente. Se o item não existir na cache, é devolvido um código de erro apropriado. Esta flag pode ser combinada com o operador bit a bit "ou" (|).

Valor de retorno

Se a operação foi bem-sucedida, é devolvido um valor de TRUE . Se ocorrer um erro, é devolvido um valor de FALSE . Se a chamada falhar, a função GetLastError Win32 pode ser chamada para determinar a causa do erro.

Consulte também

CObject Classe
Gráfico de Hierarquia
CInternetConnection Classe
CHttpConnection Classe
CFtpConnection Classe
CGopherConnection Classe