Udostępnij za pośrednictwem

Klasa CHttpFile

  • Artykuł

Udostępnia funkcje żądania i odczytywania plików na serwerze HTTP.

Składnia

class CHttpFile : public CInternetFile

Elementy członkowskie

Konstruktory chronione

Nazwa/nazwisko opis
CHttpFile::CHttpFile Tworzy obiekt CHttpFile.

Metody publiczne

Nazwa/nazwisko opis
CHttpFile::AddRequestHeaders Dodaje nagłówki do żądania wysłanego do serwera HTTP.
CHttpFile::EndRequest Kończy żądanie wysyłane do serwera HTTP za pomocą funkcji składowej SendRequestEx .
CHttpFile::GetFileURL Pobiera adres URL określonego pliku.
CHttpFile::GetObject Pobiera obiekt docelowy zlecenia w żądaniu do serwera HTTP.
CHttpFile::GetVerb Pobiera czasownik użyty w żądaniu do serwera HTTP.
CHttpFile::QueryInfo Zwraca nagłówki odpowiedzi lub żądania z serwera HTTP.
CHttpFile::QueryInfoStatusCode Pobiera kod stanu skojarzony z żądaniem HTTP i umieszcza go w podanym dwStatusCode parametrze.
CHttpFile::SendRequest Wysyła żądanie do serwera HTTP.
CHttpFile::SendRequestEx Wysyła żądanie do serwera HTTP przy użyciu metod Write lub WriteString .CInternetFile

Uwagi

Jeśli sesja internetowa odczytuje dane z serwera HTTP, musisz utworzyć wystąpienie CHttpFileprogramu .

Aby dowiedzieć się więcej o CHttpFile sposobie pracy z innymi klasami internetowymi MFC, zobacz artykuł Programowanie internetowe za pomocą usługi WinInet.

Hierarchia dziedziczenia

Obiekt CObject

CFile

CStdioFile

CInternetFile

CHttpFile

Wymagania

Nagłówek: afxinet.h

CHttpFile::AddRequestHeaders

Wywołaj tę funkcję składową, aby dodać co najmniej jeden nagłówek żądania HTTP do dojścia żądania HTTP.

BOOL AddRequestHeaders(
    LPCTSTR pstrHeaders,
    DWORD dwFlags = HTTP_ADDREQ_FLAG_ADD_IF_NEW,
    int dwHeadersLen = -1);

BOOL AddRequestHeaders(
    CString& str,
    DWORD dwFlags = HTTP_ADDREQ_FLAG_ADD_IF_NEW);

Parametry

pstrHeaders
Wskaźnik do ciągu zawierającego nagłówek lub nagłówki, które mają być dołączane do żądania. Każdy nagłówek musi zostać zakończony przez parę CR/LF.

dwFlags
Modyfikuje semantyka nowych nagłówków. Może być jednym z następujących elementów:

  • HTTP_ADDREQ_FLAG_COALESCE Scala nagłówki o tej samej nazwie, używając flagi , aby dodać pierwszy nagłówek znaleziony do kolejnego nagłówka. Na przykład polecenie "Accept: text/*", a następnie polecenie "Accept: audio/*" powoduje utworzenie pojedynczego nagłówka "Accept: text/*, audio/*". Jest to aplikacja wywołująca, aby zapewnić spójny schemat w odniesieniu do danych odbieranych przez żądania wysyłane z łączeniem lub oddzielnymi nagłówkami.

  • HTTP_ADDREQ_FLAG_REPLACE Wykonuje usuwanie i dodawanie w celu zastąpienia bieżącego nagłówka. Nazwa nagłówka zostanie użyta do usunięcia bieżącego nagłówka, a pełna wartość zostanie użyta do dodania nowego nagłówka. Jeśli wartość nagłówka jest pusta, a nagłówek zostanie znaleziony, zostanie usunięty. Jeśli wartość nagłówka nie jest pusta, zostanie zamieniona.

  • HTTP_ADDREQ_FLAG_ADD_IF_NEW dodaje tylko nagłówek, jeśli jeszcze nie istnieje. Jeśli taki istnieje, zwracany jest błąd.

  • HTTP_ADDREQ_FLAG_ADD używane z funkcją REPLACE. Dodaje nagłówek, jeśli nie istnieje.

dwHeadersLen
Długość, w znakach , pstrHeaders. Jeśli jest to wartość -1L, przyjmuje się, że wartość pstrHeaders ma być zakończona zero, a długość jest obliczana.

Str
Odwołanie do obiektu CString zawierającego nagłówek żądania lub nagłówki do dodania.

Wartość zwracana

Bezzerowe, jeśli się powiedzie; w przeciwnym razie 0. Jeśli wywołanie zakończy się niepowodzeniem, funkcja Win32 GetLastError może zostać wywołana, aby określić przyczynę błędu.

Uwagi

AddRequestHeaders Dołącza dodatkowe nagłówki w formacie swobodnym do dojścia żądania HTTP. Jest przeznaczony do użycia przez zaawansowanych klientów, którzy potrzebują szczegółowej kontroli nad dokładnym żądaniem wysłanym do serwera HTTP.

Uwaga

Aplikacja może przekazać wiele nagłówków w elementach pstrHeaders lub str dla AddRequestHeaders wywołania przy użyciu HTTP_ADDREQ_FLAG_ADD lub HTTP_ADDREQ_FLAG_ADD_IF_NEW. Jeśli aplikacja próbuje usunąć lub zamienić nagłówek przy użyciu HTTP_ADDREQ_FLAG_REMOVE lub HTTP_ADDREQ_FLAG_REPLACE, w lpszHeaders można podać tylko jeden nagłówek.

CHttpFile::CHttpFile

Ta funkcja składowa jest wywoływana w celu skonstruowania CHttpFile obiektu.

CHttpFile(
    HINTERNET hFile,
    HINTERNET hSession,
    LPCTSTR pstrObject,
    LPCTSTR pstrServer,
    LPCTSTR pstrVerb,
    DWORD_PTR dwContext);

CHttpFile(
    HINTERNET hFile,
    LPCTSTR pstrVerb,
    LPCTSTR pstrObject,
    CHttpConnection* pConnection);

Parametry

hFile
Dojście do pliku internetowego.

hSession
Dojście do sesji internetowej.

pstrObject
Wskaźnik do ciągu zawierającego CHttpFile obiekt.

pstrServer
Wskaźnik do ciągu zawierającego nazwę serwera.

pstrVerb
Wskaźnik do ciągu zawierającego metodę, która ma być używana podczas wysyłania żądania. Może to być POST, HEAD lub GET.

dwContext
Identyfikator CHttpFile kontekstu obiektu. Zobacz Uwagi, aby uzyskać więcej informacji na temat tego parametru.

Połączenie p
Wskaźnik do obiektu CHttpConnection .

Uwagi

Nigdy nie skonstruujesz obiektu bezpośrednio; zamiast tego wywołaj metodę CHttpFile CInternetSession::OpenURL lub CHttpConnection::OpenRequest .

Wartość domyślna elementu dwContext jest wysyłana przez MFC do CHttpFile obiektu z obiektu CInternetSession , który utworzył CHttpFile obiekt. Podczas wywoływania CInternetSession::OpenURL lub CHttpConnection konstruowania CHttpFile obiektu można zastąpić wartość domyślną, aby ustawić identyfikator kontekstu na wybraną wartość. Identyfikator kontekstu jest zwracany do CInternetSession::OnStatusCallback , aby podać stan obiektu, z którym został zidentyfikowany. Aby uzyskać więcej informacji na temat identyfikatora kontekstu, zobacz artykuł Internet First Steps: WinInet (Internet First Steps: WinInet: WinInet ).

CHttpFile::EndRequest

Wywołaj tę funkcję składową, aby zakończyć żądanie wysłane do serwera HTTP za pomocą funkcji składowej SendRequestEx .

BOOL EndRequest(
    DWORD dwFlags = 0,
    LPINTERNET_BUFFERS lpBuffIn = NULL,
    DWORD_PTR dwContext = 1);

Parametry

dwFlags
Flagi opisujące operację. Aby uzyskać listę odpowiednich flag, zobacz HttpEndRequest w zestawie Windows SDK.

lpBuffIn
Wskaźnik do zainicjowanego INTERNET_BUFFERS opisującego bufor wejściowy używany do operacji.

dwContext
Identyfikator kontekstu operacji CHttpFile . Zobacz Uwagi, aby uzyskać więcej informacji na temat tego parametru.

Wartość zwracana

Bezzerowe, jeśli się powiedzie; w przeciwnym razie 0. Jeśli wywołanie nie powiedzie się, określ przyczynę błędu, sprawdzając zgłoszony obiekt CInternetException .

Uwagi

Wartość domyślna dwContext jest wysyłana przez MFC do CHttpFile obiektu z obiektu CInternetSession, który utworzył CHttpFile obiekt. Podczas wywoływania CInternetSession ::OpenURL lub CHttpConnection w celu skonstruowania CHttpFile obiektu można zastąpić wartość domyślną, aby ustawić identyfikator kontekstu na wybraną wartość. Identyfikator kontekstu jest zwracany do CInternetSession::OnStatusCallback , aby podać stan obiektu, z którym został zidentyfikowany. Zobacz artykuł Internet First Steps: WinInet , aby uzyskać więcej informacji na temat identyfikatora kontekstu.

CHttpFile::GetFileURL

Wywołaj tę funkcję składową, aby uzyskać nazwę pliku HTTP jako adres URL.

virtual CString GetFileURL() const;

Wartość zwracana

Obiekt CString zawierający adres URL odwołujący się do zasobu skojarzonego z tym plikiem.

Uwagi

Użyj tej funkcji składowej dopiero po pomyślnym wywołaniu funkcji SendRequest lub w obiekcie pomyślnie utworzonym przez bibliotekę CHttpFile OpenURL.

CHttpFile::GetObject

Wywołaj tę funkcję składową, aby uzyskać nazwę obiektu skojarzonego z tym CHttpFileelementem .

CString GetObject() const;

Wartość zwracana

Obiekt CString zawierający nazwę obiektu.

Uwagi

Użyj tej funkcji składowej dopiero po pomyślnym wywołaniu funkcji SendRequest lub w obiekcie pomyślnie utworzonym przez bibliotekę CHttpFile OpenURL.

CHttpFile::GetVerb

Wywołaj tę funkcję składową, aby pobrać czasownik HTTP (lub metodę) skojarzony z tym CHttpFileelementem .

CString GetVerb() const;

Wartość zwracana

Obiekt CString zawierający nazwę czasownika HTTP (lub metody).

Uwagi

Użyj tej funkcji składowej dopiero po pomyślnym wywołaniu funkcji SendRequest lub w obiekcie pomyślnie utworzonym przez bibliotekę CHttpFile OpenURL.

CHttpFile::QueryInfo

Wywołaj tę funkcję składową, aby zwrócić nagłówki odpowiedzi lub żądania z żądania HTTP.

BOOL QueryInfo(
    DWORD dwInfoLevel,
    LPVOID lpvBuffer,
    LPDWORD lpdwBufferLength,
    LPDWORD lpdwIndex = NULL) const;

BOOL QueryInfo(
    DWORD dwInfoLevel,
    CString& str,
    LPDWORD dwIndex = NULL) const;

BOOL QueryInfo(
    DWORD dwInfoLevel,
    SYSTEMTIME* pSysTime,
    LPDWORD dwIndex = NULL) const;

Parametry

dwInfoLevel
Kombinacja atrybutu do zapytania i następujących flag, które określają typ żądanych informacji:

  • HTTP_QUERY_CUSTOM Znajduje nazwę nagłówka i zwraca tę wartość w lpvBuffer na danych wyjściowych. HTTP_QUERY_CUSTOM zgłasza potwierdzenie, jeśli nagłówek nie zostanie znaleziony.

  • HTTP_QUERY_FLAG_REQUEST_HEADERS zazwyczaj aplikacja wysyła zapytania do nagłówków odpowiedzi, ale aplikacja może również wysyłać zapytania do nagłówków żądań przy użyciu tej flagi.

  • HTTP_QUERY_FLAG_SYSTEMTIME Dla tych nagłówków, których wartość jest ciągiem daty/godziny, takim jak "Czas ostatniej modyfikacji", ta flaga zwraca wartość nagłówka jako standardową strukturę Win32 SYSTEMTIME , która nie wymaga od aplikacji analizowania danych. Jeśli używasz tej flagi, możesz użyć SYSTEMTIME przesłonięcia funkcji.

  • HTTP_QUERY_FLAG_NUMBER Dla tych nagłówków, których wartość jest liczbą, taką jak kod stanu, ta flaga zwraca dane jako liczbę 32-bitową.

Zobacz sekcję Uwagi , aby zapoznać się z listą możliwych wartości.

lpvBuffer
Wskaźnik do buforu, który odbiera informacje.

lpdwBufferLength
Podczas wprowadzania wskazuje to wartość zawierającą długość buforu danych, liczbę znaków lub bajtów. Aby uzyskać bardziej szczegółowe informacje na temat tego parametru, zobacz sekcję Uwagi .

lpdwIndex
Wskaźnik do indeksu nagłówka opartego na zera. Może mieć wartość NULL. Użyj tej flagi, aby wyliczyć wiele nagłówków o tej samej nazwie. W danych wejściowych lpdwIndex wskazuje indeks określonego nagłówka do zwrócenia. W danych wyjściowych lpdwIndex wskazuje indeks następnego nagłówka. Jeśli nie można odnaleźć następnego indeksu, zostanie zwrócony ERROR_HTTP_HEADER_NOT_FOUND.

Str
Odwołanie do obiektu CString odbierającego zwrócone informacje.

dwIndex
Wartość indeksu. Zobacz lpdwIndex.

pSysTime
Wskaźnik do struktury Win32 SYSTEMTIME .

Wartość zwracana

Bezzerowe, jeśli się powiedzie; w przeciwnym razie 0. Jeśli wywołanie zakończy się niepowodzeniem, funkcja Win32 GetLastError może zostać wywołana, aby określić przyczynę błędu.

Uwagi

Użyj tej funkcji składowej dopiero po pomyślnym wywołaniu funkcji SendRequest lub w obiekcie pomyślnie utworzonym przez bibliotekę CHttpFile OpenURL.

Z pliku można pobrać następujące typy danych:QueryInfo

  • ciągi (wartość domyślna)

  • SYSTEMTIME (dla "Data:" "Wygasa:" itp., nagłówki)

  • DWORD (dla STATUS_CODE, CONTENT_LENGTH itp.)

Gdy ciąg jest zapisywany w buforze, a funkcja składowa zakończy się powodzeniem, lpdwBufferLength zawiera długość ciągu w znakach minus 1 dla znaku null zakończenia.

Możliwe wartości dwInfoLevel obejmują:

  • HTTP_QUERY_MIME_VERSION

  • HTTP_QUERY_CONTENT_TYPE

  • HTTP_QUERY_CONTENT_TRANSFER_ENCODING

  • HTTP_QUERY_CONTENT_ID

  • HTTP_QUERY_CONTENT_DESCRIPTION

  • HTTP_QUERY_CONTENT_LENGTH

  • HTTP_QUERY_ALLOWED_METHODS

  • HTTP_QUERY_PUBLIC_METHODS

  • HTTP_QUERY_DATE

  • HTTP_QUERY_EXPIRES

  • HTTP_QUERY_LAST_MODIFIED

  • HTTP_QUERY_MESSAGE_ID

  • HTTP_QUERY_URI

  • HTTP_QUERY_DERIVED_FROM

  • HTTP_QUERY_LANGUAGE

  • HTTP_QUERY_COST

  • HTTP_QUERY_WWW_LINK

  • HTTP_QUERY_PRAGMA

  • HTTP_QUERY_VERSION

  • HTTP_QUERY_STATUS_CODE

  • HTTP_QUERY_STATUS_TEXT

  • HTTP_QUERY_RAW_HEADERS

  • HTTP_QUERY_RAW_HEADERS_CRLF

CHttpFile::QueryInfoStatusCode

Wywołaj tę funkcję składową, aby pobrać kod stanu skojarzony z żądaniem HTTP i umieścić go w podanym parametrze dwStatusCode .

BOOL QueryInfoStatusCode(DWORD& dwStatusCode) const;

Parametry

dwStatusCode
Odwołanie do kodu stanu. Kody stanu wskazują powodzenie lub niepowodzenie żądanego zdarzenia. Zobacz Uwagi dotyczące wyboru opisów kodu stanu.

Wartość zwracana

Bezzerowe, jeśli się powiedzie; w przeciwnym razie 0. Jeśli wywołanie zakończy się niepowodzeniem, funkcja Win32 GetLastError może zostać wywołana, aby określić przyczynę błędu.

Uwagi

Użyj tej funkcji składowej dopiero po pomyślnym wywołaniu funkcji SendRequest lub w obiekcie pomyślnie utworzonym przez bibliotekę CHttpFile OpenURL.

Kody stanu HTTP należą do grup wskazujących powodzenie lub niepowodzenie żądania. W poniższych tabelach przedstawiono grupy kodów stanu i najbardziej typowe kody stanu HTTP.

Grupuj Znaczenie
200-299 Powodzenie
300-399 Informacja
400-499 Błąd żądania
500-599 Błąd serwera

Typowe kody stanu HTTP:

Kod stanu Znaczenie
200 Adres URL zlokalizowany, transmisja następuje
400 Żądanie niezrozumiałe
404 Nie znaleziono żądanego adresu URL
405 Serwer nie obsługuje żądanej metody
500 Nieznany błąd serwera
503 Osiągnięto pojemność serwera

CHttpFile::SendRequest

Wywołaj tę funkcję składową, aby wysłać żądanie do serwera HTTP.

BOOL SendRequest(
    LPCTSTR pstrHeaders = NULL,
    DWORD dwHeadersLen = 0,
    LPVOID lpOptional = NULL,
    DWORD dwOptionalLen = 0);

BOOL SendRequest(
    CString& strHeaders,
    LPVOID lpOptional = NULL,
    DWORD dwOptionalLen = 0);

Parametry

pstrHeaders
Wskaźnik do ciągu zawierającego nazwę nagłówków do wysłania.

dwHeadersLen
Długość nagłówków zidentyfikowanych przez pstrHeaders.

lpOptional
Wszelkie opcjonalne dane wysyłane bezpośrednio po nagłówkach żądania. Jest to zwykle używane w przypadku operacji POST i PUT. Może to być wartość NULL, jeśli nie ma opcjonalnych danych do wysłania.

dwOptionalLen
Długość lpOptional.

strHeaders
Ciąg zawierający nazwę nagłówków wysyłanego żądania.

Wartość zwracana

Bezzerowe, jeśli się powiedzie; w przeciwnym razie 0. Jeśli wywołanie nie powiedzie się, określ przyczynę błędu, sprawdzając zgłoszony obiekt CInternetException .

CHttpFile::SendRequestEx

Wywołaj tę funkcję składową, aby wysłać żądanie do serwera HTTP.

BOOL SendRequestEx(
    DWORD dwTotalLen,
    DWORD dwFlags = HSR_INITIATE,
    DWORD_PTR dwContext = 1);

BOOL SendRequestEx(
    LPINTERNET_BUFFERS lpBuffIn,
    LPINTERNET_BUFFERS lpBuffOut,
    DWORD dwFlags = HSR_INITIATE,
    DWORD_PTR dwContext = 1);

Parametry

dwTotalLen
Liczba bajtów do wysłania w żądaniu.

dwFlags
Flagi opisujące operację. Aby uzyskać listę odpowiednich flag, zobacz HttpSendRequestEx w zestawie Windows SDK.

dwContext
Identyfikator kontekstu operacji CHttpFile . Zobacz Uwagi, aby uzyskać więcej informacji na temat tego parametru.

lpBuffIn
Wskaźnik do zainicjowanego INTERNET_BUFFERS opisującego bufor wejściowy używany do operacji.

lpBuffOut
Wskaźnik do zainicjowanego INTERNET_BUFFERS opisującego bufor wyjściowy używany do operacji.

Wartość zwracana

Jeśli operacja niezerowa się powiedzie. Jeśli wywołanie nie powiedzie się, określ przyczynę błędu, sprawdzając zgłoszony obiekt CInternetException .

Uwagi

Ta funkcja umożliwia aplikacji wysyłanie danych przy użyciu metod Write i WriteString klasy CInternetFile. Musisz znać długość danych do wysłania przed wywołaniem dowolnego przesłonięcia tej funkcji. Pierwsze zastąpienie umożliwia określenie długości danych, które mają być wysyłane. Drugie zastąpienie akceptuje wskaźniki do INTERNET_BUFFERS struktur, których można użyć do opisania buforu w bardzo szczegółowy sposób.

Po zapisaniu zawartości do pliku wywołaj metodę EndRequest , aby zakończyć operację.

Wartość domyślna dwContext jest wysyłana przez MFC do CHttpFile obiektu z obiektu CInternetSession, który utworzył CHttpFile obiekt. Podczas wywoływania CInternetSession ::OpenURL lub CHttpConnection w celu skonstruowania CHttpFile obiektu można zastąpić wartość domyślną, aby ustawić identyfikator kontekstu na wybraną wartość. Identyfikator kontekstu jest zwracany do CInternetSession::OnStatusCallback , aby podać stan obiektu, z którym został zidentyfikowany. Aby uzyskać więcej informacji na temat identyfikatora kontekstu, zobacz artykuł Internet First Steps: WinInet (Internet First Steps: WinInet: WinInet ).

Przykład

Ten fragment kodu wysyła zawartość ciągu do biblioteki DLL o nazwie MFCISAPI.DLL na serwerze LOCALHOST. Chociaż w tym przykładzie użyto tylko jednego wywołania do WriteStringmetody , użycie wielu wywołań do wysyłania danych w blokach jest akceptowalne.

CString strData = _T("Some very long data to be POSTed here!");
pServer = session.GetHttpConnection(_T("localhost"));
pFile = pServer->OpenRequest(CHttpConnection::HTTP_VERB_POST,
                             _T("/MFCISAPI/MFCISAPI.dll?"));
pFile->SendRequestEx(strData.GetLength());

pFile->WriteString(strData);
pFile->EndRequest();

Zobacz też

Klasa CInternetFile
Wykres hierarchii
Klasa CInternetFile
Klasa CGopherFile
Klasa CHttpConnection