共用方式為


CInternetSession 類別

建立和初始化單一或多個同時網際網路工作階段,並視需要描述您與 Proxy 伺服器的連接。

語法

class CInternetSession : public CObject

成員

公用建構函式

名稱 描述
CInternetSession::CInternetSession 建構 CInternetSession 物件。

公用方法

名稱 描述
CInternetSession::Close 當網際網路工作階段終止時,關閉網際網路連線。
CInternetSession::EnableStatusCallback 建立狀態回呼常式。
CInternetSession::GetContext 當網際網路工作階段終止時,關閉網際網路連線。
CInternetSession::GetCookie 傳回指定 URL 及其所有父代 URL 的 Cookie。
CInternetSession::GetCookieLength 擷取變數,指定儲存在緩衝區中 Cookie 的長度。
CInternetSession::GetFtpConnection 使用伺服器開啟 FTP 工作階段。 登入使用者。
CInternetSession::GetGopherConnection 為嘗試開啟連線的應用程式開啟 gopher 伺服器。
CInternetSession::GetHttpConnection 為嘗試開啟連線的應用程式開啟 HTTP 伺服器。
CInternetSession::OnStatusCallback 啟用狀態回呼時,更新作業的狀態。
CInternetSession::OpenURL 剖析並開啟 URL。
CInternetSession::SetCookie 設定指定 URL 的 Cookie。
CInternetSession::SetOption 設定網際網路工作階段的選項。

公用運算子

名稱 描述
CInternetSession::operator HINTERNET 目前網際網路工作階段的控制代碼。

備註

如果您的網際網路連線必須在應用程式持續期間維護,您可以建立類別 CWinApp 的成員 CInternetSession

建立網際網路工作階段之後,您可以呼叫 OpenURLCInternetSession 接著呼叫全域函式 AfxParseURL 來為您剖析 URL。 不論其通訊協定類型為何,CInternetSession 會為您解譯 URL 並加以管理。 可以處理以 URL 資源 "file://" 識別之本機檔案的要求。 如果您傳遞給 OpenURL 的名稱是本機檔案,則其會傳回 CStdioFile 物件的指標。

如果您使用 OpenURL 在網際網路伺服器上開啟 URL,您可以從網站讀取資訊。 如果您想要在位於伺服器上的檔案上執行服務特定 (例如 HTTP、FTP 或 Gopher) 動作,您必須與該伺服器建立適當的連線。 若要直接開啟特定服務的特定連線類型,請使用下列其中一個成員函式:

SetOption 可讓您設定工作階段的查詢選項,例如逾時值、重試次數等等。

CInternetSession 成員函式 SetCookieGetCookieGetCookieLength 提供管理 Win32 Cookie 資料庫的方法,讓伺服器和指令碼維護用戶端工作站的狀態資訊。

如需基本網際網路程式設計工作的詳細資訊,請參閱網際網路第一個步驟:WinInet一文。 如需使用 MFC WinInet 類別的一般資訊,請參閱使用 WinInet 進行網際網路程式設計一文。

注意

CInternetSession 會針對不支援的服務類型擲回 AfxThrowNotSupportedException。 目前僅支援下列服務類型:FTP、HTTP、Gopher 和檔案。

繼承階層架構

CObject
CInternetSession

需求

標頭: afxinet.h

CInternetSession::CInternetSession

建立 CInternetSession 物件時,會呼叫這個成員函式。

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

參數

pstrAgent
字串的指標,可識別呼叫網際網路函式的應用程式或實體名稱 (例如「Microsoft 網際網路瀏覽器」)。 如果 pstrAgentNULL (預設值),則架構會呼叫全域函式 AfxGetAppName,這會傳回包含應用程式名稱的 null 終止字串。 某些通訊協定會使用此字串來向伺服器識別應用程式。

dwContext
作業的內容識別碼。 dwContext 會識別 CInternetSession::OnStatusCallback 所傳回的作業狀態資訊。 預設值設定為 1;不過,您可以明確指派作業的特定內容識別碼。 物件及其執行的任何工作都會與該內容識別碼相關聯。

dwAccessType
所需的存取類型。 以下是有效的值,正好提供其中一個值:

  • INTERNET_OPEN_TYPE_PRECONFIG 在登錄中使用預先設定的設定進行連線。 此存取類型會設定為預設值。 若要透過 TIS Proxy 連線,請將 dwAccessType 設定為此值;接著,您可以適當地設定登錄。

  • INTERNET_OPEN_TYPE_DIRECT 直接連線到網際網路。

  • INTERNET_OPEN_TYPE_PROXY 透過 CERN Proxy 連線。

如需與不同類型 Proxy 連線的詳細資訊,請參閱一般 FTP 用戶端應用程式中的步驟

pstrProxyName
如果 dwAccessType 設定為 INTERNET_OPEN_TYPE_PROXY,則為慣用 CERN Proxy 的名稱。 預設值為 NULL

pstrProxyBypass
字串的指標,其中包含伺服器位址的選擇性清單。 使用 Proxy 存取時,可能會略過這些位址。 如果提供 NULL 值,則會從登錄讀取略過清單。 只有當 dwAccessType 設定為 INTERNET_OPEN_TYPE_PROXY 時,這個參數才有意義。

dwFlags
表示各種快取選項。 預設值會設定為 0。 可能的值包括:

  • INTERNET_FLAG_DONT_CACHE 不要在本機或任何閘道伺服器中快取資料。

  • INTERNET_FLAG_OFFLINE 僅透過持續性快取滿足下載作業。 如果快取中沒有項目,則會傳回適當的錯誤碼。 此旗標可以與位元 "or" (|) 運算子合併使用。

備註

CInternetSession 是應用程式所呼叫的第一個網際網路函式。 會初始化內部資料結構,並為應用程式的未來呼叫做好準備。

如果無法開啟網際網路連線,CInternetSession 會擲回 AfxThrowInternetException

範例

請參閱 CFtpFileFind 的範例。

CInternetSession::Close

當您的應用程式使用 CInternetSession 物件完成時,請呼叫這個成員函式。

virtual void Close();

範例

請參閱 CFtpFileFind 的範例。

CInternetSession::EnableStatusCallback

呼叫此成員函式以啟用狀態回呼。

BOOL EnableStatusCallback(BOOL bEnable = TRUE);

參數

bEnable
指定回呼已啟用或停用。 預設值為 TRUE

傳回值

如果成功則為非零;否則為 0。 如果呼叫失敗,請檢查擲回的 CInternetException 對象來判斷失敗的原因。

備註

處理狀態回呼時,您可以在應用程式的狀態列上提供作業進度的狀態 (例如解析名稱、連線到伺服器等等)。 在長期作業期間,顯示作業狀態特別理想。

由於回呼會在要求處理期間發生,因此應用程式應該在回呼中盡量花費最少的時間,以防止前往網路的資料輸送量降低。 例如,在回呼中放置對話方塊可能是伺服器終止要求的冗長作業。

只要有任何回呼擱置中,就無法移除狀態回呼。

若要以非同步方式處理任何作業,您必須建立自己的執行緒,或使用不含 MFC 的 WinInet 函式。

CInternetSession::GetContext

呼叫這個成員函式以取得特定應用程式工作階段的內容值。

DWORD_PTR GetContext() const;

傳回值

應用程式定義的內容識別碼。

備註

OnStatusCallback 會使用 GetContext 傳回的內容識別碼來報告特定應用程式的狀態。 例如,當使用者啟動涉及傳回狀態資訊的網際網路要求時,狀態回呼會使用內容識別碼來報告該特定要求的狀態。 如果使用者啟動兩個都涉及傳回狀態資訊的個別網際網路要求,OnStatusCallback 會使用內容識別碼傳回其對應要求的狀態。 因此,內容識別碼會用於所有狀態回呼作業,且與工作階段相關聯,直到工作階段結束為止。

如需非同步作業的詳細資訊,請參閱網際網路第一個步驟:WinInet 一文。

CInternetSession::GetCookie

此成員函式會實作 Win32 函式 InternetGetCookie 的行為,如 Windows SDK 中所述。

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

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

參數

pstrUrl
字串的指標,其中包含 URL。

pstrCookieName
字串的指標,其中包含要取得指定 URL 的 Cookie 名稱。

pstrCookieData
在第一個多載中,字串的指標,其中包含接收 Cookie 資料的緩衝區位址。 這個值可以是 NULL。 在第二個多載中,要接收 Cookie 資料的 CString 物件參考。

dwBufLen
變數,指定 pstrCookieData 緩衝區的大小。 如果函式成功,緩衝區會收到複製到 pstrCookieData 緩衝區的資料量。 如果 pstrCookieDataNULL,此參數會接收值,指定複製所有 Cookie 資料所需的緩衝區大小。

傳回值

如果成功則傳回 TRUE,否則傳回 FALSE。 如果呼叫失敗,請呼叫 Win32 函式 GetLastError,以判斷錯誤的原因。 套用下列錯誤值:

  • ERROR_NO_MORE_ITEMS 指定 URL 及其所有父代都沒有 Cookie。

  • ERROR_INSUFFICIENT_BUFFER 傳入 dwBufLen 的值不足以複製所有 Cookie 資料。 dwBufLen 中傳回的值是取得所有資料所需的緩衝區大小。

備註

在第二個多載中,MFC 會將 Cookie 資料擷取到提供的 CString 物件中。

CInternetSession::GetCookieLength

呼叫這個成員函式,以取得儲存在緩衝區中的 Cookie 長度。

static DWORD GetCookieLength(
    LPCTSTR pstrUrl,
    LPCTSTR pstrCookieName);

參數

pstrUrl
字串的指標,其中包含 URL

pstrCookieName
字串的指標,其中包含 Cookie 的名稱。

傳回值

DWORD 值,指出儲存在緩衝區中的 Cookie 長度。 如果沒有 pstrCookieName 所指出名稱的 Cookie 存在,則為零。

備註

這個值是由 GetCookie 使用。

CInternetSession::GetFtpConnection

呼叫此成員函式來建立 FTP 連線,並取得 CFtpConnection 物件的指標。

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

參數

pstrServer
字串的指標,其中包含 FTP 伺服器名稱。

pstrUserName
null 終止字串的指標,指定要登入的使用者名稱。 如果為 NULL,則預設值為匿名。

pstrPassword
null 終止字串的指標,指定要用來登入的密碼。 如果 pstrPasswordpstrUserName 都是 NULL,則預設的匿名密碼是使用者的電子郵件名稱。 如果 pstrPasswordNULL (或空字串),但 pstrUserName 不是 NULL,則會使用空白密碼。 下表描述 pstrUserNamepstrPassword 四種可能設定的行為:

pstrUserName pstrPassword 傳送至 FTP 伺服器的使用者名稱 傳送至 FTP 伺服器的密碼
NULL" " NULL" " "anonymous" 使用者的電子郵件名稱
NULL 字串 NULL" " pstrUserName
NULL NULL 字串 錯誤 錯誤
NULL 字串 NULL 字串 pstrUserName pstrPassword

nPort
數字,識別伺服器上要使用的 TCP/IP 連接埠。

bPassive
指定這個 FTP 工作階段的被動或主動模式。 如果設定為 TRUE,則會將 Win32 API dwFlag 設定為 INTERNET_FLAG_PASSIVE

傳回值

CFtpConnection 物件的指標。 如果呼叫失敗,請檢查擲回的 CInternetException 對象來判斷失敗的原因。

備註

GetFtpConnection 連線到 FTP 伺服器,並建立及傳回 CFTPConnection 物件的指標。 不會在伺服器上執行任何特定作業。 例如,如果您想要讀取或寫入檔案,則必須以個別步驟執行這些作業。 如需搜尋檔案、開啟檔案,以及讀取或寫入檔案的詳細資訊,請參閱類別 CFtpConnectionCFtpFileFind。 如需執行常見 FTP 連線工作的步驟,請參閱使用 WinInet 進行網際網路程式設計一文。

範例

請參閱 CFtpFileFind 的範例。

CInternetSession::GetGopherConnection

呼叫此成員函式來建立新 Gopher 連線,並取得 CGopherConnection 物件的指標。

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

參數

pstrServer
字串的指標,其中包含 Gopher 伺服器名稱。

pstrUserName
字串的指標,其中包含使用者名稱。

pstrPassword
字串的指標,其中包含存取密碼。

nPort
數字,識別伺服器上要使用的 TCP/IP 連接埠。

傳回值

CGopherConnection 物件的指標。 如果呼叫失敗,請檢查擲回的 CInternetException 對象來判斷失敗的原因。

備註

GetGopherConnection 連線到 Gopher 伺服器,並建立及傳回 CGopherConnection 物件的指標。 不會在伺服器上執行任何特定作業。 例如,如果您想要讀取或寫入資料,則必須以個別步驟執行這些作業。 如需搜尋檔案、開啟檔案,以及讀取或寫入檔案的詳細資訊,請參閱類別 CGopherConnectionCGopherFileCGopherFileFind。 如需瀏覽 FTP 網站的詳細資訊,請參閱成員函式 OpenURL。 如需執行常見 Gopher 連線工作的步驟,請參閱使用 WinInet 進行網際網路程式設計一文。

CInternetSession::GetHttpConnection

呼叫此成員函式來建立 HTTP 連線,並取得 CHttpConnection 物件的指標。

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);

參數

pstrServer
字串的指標,其中包含 HTTP 伺服器名稱。

nPort
數字,識別伺服器上要使用的 TCP/IP 連接埠。

pstrUserName
字串的指標,其中包含使用者名稱。

pstrPassword
字串的指標,其中包含存取密碼。

dwflags
INTERNET_FLAG_* 旗標的任意組合。 如需 dwFlags 值的描述,請參閱 CHttpConnection::OpenRequest 的 [備註] 區段中的資料表。

傳回值

CHttpConnection 物件的指標。 如果呼叫失敗,請檢查擲回的 CInternetException 對象來判斷失敗的原因。

備註

GetHttpConnection 連線到 HTTP 伺服器,並建立及傳回 CHttpConnection 物件的指標。 不會在伺服器上執行任何特定作業。 例如,如果您想要查詢 HTTP 標頭,則必須以個別步驟執行這項作業。 如需您可以使用與 HTTP 伺服器的連線來執行之作業的詳細資訊,請參閱類別 CHttpConnectionCHttpFile。 如需瀏覽 HTTP 網站的詳細資訊,請參閱成員函式 OpenURL。 如需執行常見 HTTP 連線工作的步驟,請參閱使用 WinInet 進行網際網路程式設計一文。

CInternetSession::OnStatusCallback

架構會呼叫此成員函式,以在啟用狀態回呼且作業擱置時更新狀態。

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

參數

dwContext
應用程式提供的內容值。

dwInternetStatus
狀態碼,指出進行回呼的原因。 如需可能值的資料表,請參閱備註

lpvStatusInformation
緩衝區的指標,其中包含與這個回呼相關的資訊。

dwStatusInformationLength
lpvStatusInformation 的大小。

備註

您必須先呼叫 EnableStatusCallback,才能利用狀態回呼。

dwInternetStatus 參數指出正在執行的作業,並決定 lpvStatusInformation 的內容。 dwStatusInformationLength 指出 lpvStatusInformation 中所包含資料的長度。 dwInternetStatus 的下列狀態值定義如下:

意義
INTERNET_STATUS_RESOLVING_NAME 查閱包含在 lpvStatusInformation 中名稱的 IP 位址。
INTERNET_STATUS_NAME_RESOLVED 成功找到包含在 lpvStatusInformation 中名稱的 IP 位址。
INTERNET_STATUS_CONNECTING_TO_SERVER 連線到 lpvStatusInformation 指向的通訊端位址 (SOCKADDR)。
INTERNET_STATUS_CONNECTED_TO_SERVER 成功連線到 lpvStatusInformation 指向的通訊端位址 (SOCKADDR)。
INTERNET_STATUS_SENDING_REQUEST 將資訊要求傳送至伺服器。 lpvStatusInformation 參數為 NULL
INTERNET_STATUS_REQUEST_SENT 成功將資訊要求傳送至伺服器。 lpvStatusInformation 參數為 NULL
INTERNET_STATUS_RECEIVING_RESPONSE 等候伺服器回應要求。 lpvStatusInformation 參數為 NULL
INTERNET_STATUS_RESPONSE_RECEIVED 成功從伺服器接收回應。 lpvStatusInformation 參數為 NULL
INTERNET_STATUS_CLOSING_CONNECTION 關閉與伺服器的連線。 lpvStatusInformation 參數為 NULL
INTERNET_STATUS_CONNECTION_CLOSED 成功關閉與伺服器的連線。 lpvStatusInformation 參數為 NULL
INTERNET_STATUS_HANDLE_CREATED Win32 API 函式 InternetConnect 用來指出已建立新的控制代碼。 如果連線耗費太久的時間,這可讓應用程式從另一個執行緒呼叫 Win32 函式 InternetCloseHandle。 如需這些函式的詳細資訊,請參閱 Windows SDK。
INTERNET_STATUS_HANDLE_CLOSING 成功終止此控制代碼值。

覆寫此成員函式,以在執行狀態回呼常式之前要求一些動作。

注意

狀態回呼需要執行緒狀態保護。 如果您在共用程式庫中使用 MFC,請將下列這一行新增至覆寫的開頭:

AFX_MANAGE_STATE(AfxGetAppModuleState());

如需非同步作業的詳細資訊,請參閱網際網路第一個步驟:WinInet 一文。

CInternetSession::OpenURL

呼叫此成員函式,將指定的要求傳送至 HTTP 伺服器,並允許用戶端指定額外的 RFC822、MIME 或 HTTP 標頭,以連同要求一起傳送。

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

參數

pstrURL
要開始讀取的 URL 名稱指標。 僅支援開頭為 file:ftp:gopher:http: 的 URL。 如果 pstrURLNULL,則判斷提示。

dwContext
以回呼中傳回控制代碼傳遞的應用程式定義值。

dwFlags
描述如何處理此連線的旗標。 如需有效旗標的詳細資訊,請參閱備註。 有效的旗標為:

  • INTERNET_FLAG_TRANSFER_ASCII 預設值。 以 ASCII 文字的形式傳輸檔案。

  • INTERNET_FLAG_TRANSFER_BINARY 以二進位檔案的形式傳輸檔案。

  • INTERNET_FLAG_RELOAD 即使是本機快取,也會從網路取得資料。

  • INTERNET_FLAG_DONT_CACHE 不要在本機或任何閘道中快取資料。

  • INTERNET_FLAG_SECURE 此旗標僅適用於 HTTP 要求。 會要求使用安全通訊端層或 PCT 線上進行安全交易。

  • INTERNET_OPEN_FLAG_USE_EXISTING_CONNECT 可能的話,請針對 OpenUrl 所產生的新要求重複使用伺服器的現有連線,而不是為每個連線要求建立新的工作階段。

  • INTERNET_FLAG_PASSIVE 用於 FTP 網站。 使用被動 FTP 語意。 與 OpenURLCInternetConnection 搭配使用。

pstrHeaders
字串的指標,其中包含要傳送至 HTTP 伺服器的標頭。

dwHeadersLength
額外標頭的長度 (以字元為單位)。 如果這是 -1LpstrHeaders 為非 NULL,則會假設 pstrHeaders 為零終止,並計算長度。

傳回值

僅傳回 FTP、GOPHER、HTTP 和 FILE 類型網際網路服務的檔案控制代碼。 如果剖析失敗,則傳回 NULL

OpenURL 傳回的指標取決於 pstrURL 的服務類型。 下表說明 OpenURL 可以傳回的可能指標。

URL 類型 傳回
file:// CStdioFile*
http:// CHttpFile*
gopher:// CGopherFile*
ftp:// CInternetFile*

備註

參數 dwFlags 必須包含 INTERNET_FLAG_TRANSFER_ASCIIINTERNET_FLAG_TRANSFER_BINARY,但不能同時包含兩者。 這些剩餘旗標可以與位元 "or" (|) 運算子合併使用。

OpenURL,會包裝 Win32 函式 InternetOpenURL,只允許從網際網路伺服器下載、擷取和讀取資料。 OpenURL 不允許遠端位置上的檔案操作,因此不需要任何 CInternetConnection 物件。

若要使用連線特定 (也就是通訊協定特定) 函式,例如寫入檔案,您必須開啟工作階段,然後開啟特定類型的連線,接著使用該連線以所需的模式開啟檔案。 如需連線特定函式的詳細資訊,請參閱 CInternetConnection

CInternetSession::operator HINTERNET

使用此運算子取得目前網際網路工作階段的 Windows 控制代碼。

operator HINTERNET() const;

CInternetSession::SetCookie

設定指定 URL 的 Cookie。

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

參數

pstrUrl
null 終止字串的指標,指定應該設定 Cookie 的 URL。

pstrCookieName
字串的指標,其中包含 Cookie 的名稱。

pstrCookieData
字串的指標,其中包含與 URL 相關聯的實際字串資料。

傳回值

如果成功則傳回 TRUE,否則傳回 FALSE。 若要取得特定錯誤碼,請呼叫 GetLastError

備註

此成員函式會實作 Win32 訊息 InternetSetCookie 的行為,如 Windows SDK 中所述。

CInternetSession::SetOption

呼叫此成員函式以設定網際網路工作階段的選項。

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

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

參數

dwOption
要設定的網際網路選項。 如需可能選項的清單,請參閱 Windows SDK 中的選項旗標

lpBuffer
包含選項設定的緩衝區。

dwBufferLength
lpBuffer 的長度或 dwValue 的大小。

dwValue
包含選項設定的 DWORD

dwFlags
表示各種快取選項。 預設值會設定為 0。 可能的值包括:

  • INTERNET_FLAG_DONT_CACHE 不要在本機或任何閘道伺服器中快取資料。

  • INTERNET_FLAG_OFFLINE 僅透過持續性快取滿足下載作業。 如果快取中沒有項目,則會傳回適當的錯誤碼。 此旗標可以與位元 "or" (|) 運算子合併使用。

傳回值

如果作業成功,則會傳回 TRUE 的值。 如果發生錯誤,將會傳回 FALSE 的值。 如果呼叫失敗,則可能會呼叫 Win32 函式 GetLastError 以判斷錯誤的原因。

另請參閱

CObject 類別
階層架構圖表
CInternetConnection 類別
CHttpConnection 類別
CFtpConnection 類別
CGopherConnection 類別