CHttpFile, classe

Fournit les fonctionnalités permettant de demander et de lire des fichiers sur un serveur HTTP.

Syntaxe

class CHttpFile : public CInternetFile

Membres

Constructeurs protégés

Méthodes publiques

Notes

Si votre session Internet lit des données à partir d’un serveur HTTP, vous devez créer une instance de CHttpFile.

Pour en savoir plus sur CHttpFile l’utilisation des autres classes Internet MFC, consultez l’article Programmation Internet avec WinInet.

Hiérarchie d'héritage

CObject

CFile

CStdioFile

CInternetFile

CHttpFile

Spécifications

En-tête : afxinet.h

CHttpFile ::AddRequestHeaders

Appelez cette fonction membre pour ajouter un ou plusieurs en-têtes de requête HTTP au handle de requête 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);

Paramètres

pstrHeaders
Pointeur vers une chaîne contenant l’en-tête ou les en-têtes à ajouter à la requête. Chaque en-tête doit être arrêté par une paire CR/LF.

dwFlags
Modifie la sémantique des nouveaux en-têtes. Il peut s'agir d'une des méthodes suivantes :

• HTTP_ADDREQ_FLAG_COALESCE fusionne les en-têtes du même nom, en utilisant l’indicateur pour ajouter le premier en-tête trouvé à l’en-tête suivant. Par exemple, « Accept : text/* » suivi de « Accept : audio/* » entraîne la formation de l’en-tête unique « Accept : text/*, audio/* ». Il incombe à l’application appelante de garantir un schéma cohérent en ce qui concerne les données reçues par les demandes envoyées avec des en-têtes coalescés ou distincts.

• HTTP_ADDREQ_FLAG_REPLACE Effectue une suppression et ajoute pour remplacer l’en-tête actuel. Le nom de l’en-tête sera utilisé pour supprimer l’en-tête actuel et la valeur complète sera utilisée pour ajouter le nouvel en-tête. Si la valeur d’en-tête est vide et que l’en-tête est trouvé, il est supprimé. S’il n’est pas vide, la valeur d’en-tête est remplacée.

• HTTP_ADDREQ_FLAG_ADD_IF_NEW ajoute uniquement l’en-tête s’il n’existe pas déjà. S’il en existe un, une erreur est retournée.

• HTTP_ADDREQ_FLAG_ADD utilisé avec REPLACE. Ajoute l’en-tête s’il n’existe pas.

dwHeadersLen
Longueur, en caractères, de pstrHeaders. S’il s’agit de -1L, pstrHeaders est supposé être arrêté zéro et la longueur est calculée.

str
Référence à un objet CString contenant l’en-tête ou les en-têtes de requête à ajouter.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0. Si l’appel échoue, la fonction Win32 GetLastError peut être appelée pour déterminer la cause de l’erreur.

Notes

AddRequestHeaders ajoute des en-têtes de format libre supplémentaires au handle de requête HTTP. Elle est destinée à être utilisée par des clients sophistiqués qui ont besoin d’un contrôle détaillé sur la requête exacte envoyée au serveur HTTP.

CHttpFile ::CHttpFile

Cette fonction membre est appelée pour construire un CHttpFile objet.

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

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

Paramètres

hFile
Handle vers un fichier Internet.

hSession
Handle vers une session Internet.

pstrObject
Pointeur vers une chaîne contenant l’objet CHttpFile .

pstrServer
Pointeur vers une chaîne contenant le nom du serveur.

pstrVerb
Pointeur vers une chaîne contenant la méthode à utiliser lors de l’envoi de la requête. Peut être POST, HEAD ou GET.

dwContext
Identificateur de contexte de l’objet CHttpFile . Pour plus d’informations sur ce paramètre, consultez Les remarques .

pConnection
Pointeur vers un objet CHttpConnection .

Notes

Vous ne construisez jamais un CHttpFile objet directement ; appelez plutôt CInternetSession ::OpenURL ou CHttpConnection ::OpenRequest à la place.

La valeur par défaut est dwContext envoyée par MFC à l’objet CHttpFile à partir de l’objet CInternetSession qui a créé l’objet CHttpFile . Lorsque vous appelez ou CHttpConnection construisez CInternetSession::OpenURL un CHttpFile objet, vous pouvez remplacer la valeur par défaut pour définir l’identificateur de contexte sur une valeur de votre choix. L’identificateur de contexte est retourné à CInternetSession ::OnStatusCallback pour fournir l’état sur l’objet avec lequel il est identifié. Pour plus d’informations sur l’identificateur de contexte, consultez l’article Sur Internet First Steps : WinInet .

CHttpFile ::EndRequest

Appelez cette fonction membre pour mettre fin à une requête envoyée à un serveur HTTP avec la fonction membre SendRequestEx .

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

Paramètres

dwFlags
Indicateurs décrivant l’opération. Pour obtenir la liste des indicateurs appropriés, consultez HttpEndRequest dans le Kit de développement logiciel (SDK) Windows.

lpBuffIn
Pointeur vers un INTERNET_BUFFERS initialisé qui décrit la mémoire tampon d’entrée utilisée pour l’opération.

dwContext
Identificateur de contexte de l’opération CHttpFile . Pour plus d’informations sur ce paramètre, consultez Les remarques.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0. Si l’appel échoue, déterminez la cause de l’échec en examinant l’objet CInternetException levée.

Notes

La valeur par défaut de dwContext est envoyée par MFC à l’objet CHttpFile à partir de l’objet CInternetSession qui a créé l’objet CHttpFile . Lorsque vous appelez CInternetSession ::OpenURL ou CHttpConnection pour construire un CHttpFile objet, vous pouvez remplacer la valeur par défaut pour définir l’identificateur de contexte sur une valeur de votre choix. L’identificateur de contexte est retourné à CInternetSession ::OnStatusCallback pour fournir l’état sur l’objet avec lequel il est identifié. Pour plus d’informations sur l’identificateur de contexte, consultez l’article Sur Internet First Steps : WinInet .

CHttpFile ::GetFileURL

Appelez cette fonction membre pour obtenir le nom du fichier HTTP en tant qu’URL.

virtual CString GetFileURL() const;

Valeur de retour

Objet CString contenant une URL référençant la ressource associée à ce fichier.

Notes

Utilisez cette fonction membre uniquement après un appel réussi à SendRequest ou sur un CHttpFile objet créé avec succès par OpenURL.

CHttpFile ::GetObject

Appelez cette fonction membre pour obtenir le nom de l’objet associé à ce CHttpFile.

CString GetObject() const;

Valeur de retour

Objet CString contenant le nom de l’objet.

Notes

Utilisez cette fonction membre uniquement après un appel réussi à SendRequest ou sur un CHttpFile objet créé avec succès par OpenURL.

CHttpFile ::GetVerb

Appelez cette fonction membre pour obtenir le verbe HTTP (ou méthode) associé à ce CHttpFile.

CString GetVerb() const;

Valeur de retour

Objet CString contenant le nom du verbe HTTP (ou méthode).

Notes

Utilisez cette fonction membre uniquement après un appel réussi à SendRequest ou sur un CHttpFile objet créé avec succès par OpenURL.

CHttpFile ::QueryInfo

Appelez cette fonction membre pour retourner des en-têtes de réponse ou de requête à partir d’une requête 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;

Paramètres

dwInfoLevel
Combinaison de l’attribut à interroger et des indicateurs suivants qui spécifient le type d’informations demandées :

• HTTP_QUERY_CUSTOM Recherche le nom de l’en-tête et retourne cette valeur dans lpvBuffer en sortie. HTTP_QUERY_CUSTOM lève une assertion si l’en-tête est introuvable.

• HTTP_QUERY_FLAG_REQUEST_HEADERS Généralement, l’application interroge les en-têtes de réponse, mais une application peut également interroger des en-têtes de requête à l’aide de cet indicateur.

• HTTP_QUERY_FLAG_SYSTEMTIME Pour ces en-têtes dont la valeur est une chaîne de date/heure, telle que « Last-Modified-Time », cet indicateur retourne la valeur d’en-tête en tant que structure SYSTEMTIME Win32 standard qui ne nécessite pas que l’application analyse les données. Si vous utilisez cet indicateur, vous pouvez utiliser le SYSTEMTIME remplacement de la fonction.

• HTTP_QUERY_FLAG_NUMBER Pour ces en-têtes dont la valeur est un nombre, tel que le code d’état, cet indicateur retourne les données sous la forme d’un nombre 32 bits.

Consultez la section Remarques pour obtenir la liste des valeurs possibles.

lpvBuffer
Pointeur vers la mémoire tampon qui reçoit les informations.

lpdwBufferLength
Lors de l’entrée, cela pointe vers une valeur contenant la longueur de la mémoire tampon de données, en nombre de caractères ou d’octets. Pour plus d’informations sur ce paramètre, consultez la section Remarques .

lpdwIndex
Pointeur vers un index d’en-tête de base zéro. Sa valeur peut être NULL. Utilisez cet indicateur pour énumérer plusieurs en-têtes portant le même nom. Lors de l’entrée, lpdwIndex indique l’index de l’en-tête spécifié à retourner. En sortie, lpdwIndex indique l’index de l’en-tête suivant. Si l’index suivant est introuvable, ERROR_HTTP_HEADER_NOT_FOUND est retourné.

str
Référence à l’objet CString qui reçoit les informations retournées.

dwIndex
Valeur d’index. Voir lpdwIndex.

pSysTime
Pointeur vers une structure SYSTEMTIME Win32.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0. Si l’appel échoue, la fonction Win32 GetLastError peut être appelée pour déterminer la cause de l’erreur.

Notes

Utilisez cette fonction membre uniquement après un appel réussi à SendRequest ou sur un CHttpFile objet créé avec succès par OpenURL.

Vous pouvez récupérer les types de données suivants à partir de QueryInfo:

• chaînes (valeur par défaut)

• SYSTEMTIME (pour « Data : » « Expire : » etc. en-têtes)

• DWORD (pour STATUS_CODE, CONTENT_LENGTH, etc.)

Lorsqu’une chaîne est écrite dans la mémoire tampon et que la fonction membre réussit, lpdwBufferLength contient la longueur de la chaîne en caractères moins 1 pour le caractère NULL de fin.

Les valeurs dwInfoLevel possibles sont les suivantes :

• 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

Appelez cette fonction membre pour obtenir le code d’état associé à une requête HTTP et le placer dans le paramètre dwStatusCode fourni.

BOOL QueryInfoStatusCode(DWORD& dwStatusCode) const;

Paramètres

dwStatusCode
Référence à un code d’état. Les codes d’état indiquent la réussite ou l’échec de l’événement demandé. Consultez les remarques pour une sélection de descriptions de code d’état.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0. Si l’appel échoue, la fonction Win32 GetLastError peut être appelée pour déterminer la cause de l’erreur.

Notes

Utilisez cette fonction membre uniquement après un appel réussi à SendRequest ou sur un CHttpFile objet créé avec succès par OpenURL.

Les codes d’état HTTP appartiennent à des groupes indiquant la réussite ou l’échec de la requête. Les tableaux suivants décrivent les groupes de codes d’état et les codes d’état HTTP les plus courants.

Codes d’état HTTP courants :

CHttpFile ::SendRequest

Appelez cette fonction membre pour envoyer une requête à un serveur 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);

Paramètres

pstrHeaders
Pointeur vers une chaîne contenant le nom des en-têtes à envoyer.

dwHeadersLen
Longueur des en-têtes identifiés par pstrHeaders.

lpOptional
Toutes les données facultatives à envoyer immédiatement après les en-têtes de requête. Cela est généralement utilisé pour les opérations POST et PUT. Cela peut être NULL s’il n’existe aucune donnée facultative à envoyer.

dwOptionalLen
Longueur de lpOptional.

strHeaders
Chaîne contenant le nom des en-têtes de la demande envoyée.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0. Si l’appel échoue, déterminez la cause de l’échec en examinant l’objet CInternetException levée.

CHttpFile ::SendRequestEx

Appelez cette fonction membre pour envoyer une requête à un serveur 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);

Paramètres

dwTotalLen
Nombre d’octets à envoyer dans la requête.

dwFlags
Indicateurs décrivant l’opération. Pour obtenir la liste des indicateurs appropriés, consultez HttpSendRequestEx dans le Kit de développement logiciel (SDK) Windows.

dwContext
Identificateur de contexte de l’opération CHttpFile . Pour plus d’informations sur ce paramètre, consultez Les remarques.

lpBuffIn
Pointeur vers un INTERNET_BUFFERS initialisé qui décrit la mémoire tampon d’entrée utilisée pour l’opération.

lpBuffOut
Pointeur vers un INTERNET_BUFFERS initialisé qui décrit la mémoire tampon de sortie utilisée pour l’opération.

Valeur de retour

Différent de zéro s’il réussit. Si l’appel échoue, déterminez la cause de l’échec en examinant l’objet CInternetException levée.

Notes

Cette fonction permet à votre application d’envoyer des données à l’aide des méthodes Write et WriteString de CInternetFile. Vous devez connaître la longueur des données à envoyer avant d’appeler l’un des remplacements de cette fonction. Le premier remplacement vous permet de spécifier la longueur des données que vous souhaitez envoyer. Le deuxième remplacement accepte les pointeurs vers INTERNET_BUFFERS structures, qui peuvent être utilisées pour décrire la mémoire tampon en détail.

Une fois le contenu écrit dans le fichier, appelez EndRequest pour mettre fin à l’opération.

La valeur par défaut de dwContext est envoyée par MFC à l’objet CHttpFile à partir de l’objet CInternetSession qui a créé l’objet CHttpFile . Lorsque vous appelez CInternetSession ::OpenURL ou CHttpConnection pour construire un CHttpFile objet, vous pouvez remplacer la valeur par défaut pour définir l’identificateur de contexte sur une valeur de votre choix. L’identificateur de contexte est retourné à CInternetSession ::OnStatusCallback pour fournir l’état sur l’objet avec lequel il est identifié. Pour plus d’informations sur l’identificateur de contexte, consultez l’article Sur Internet First Steps : WinInet .

Exemple

Ce fragment de code envoie le contenu d’une chaîne à une DLL nommée MFCISAPI.DLL sur le serveur LOCALHOST. Bien que cet exemple utilise un seul appel, WriteStringl’utilisation de plusieurs appels pour envoyer des données dans des blocs est acceptable.

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

Voir aussi

CInternetFile, classe
Graphique hiérarchique
CInternetFile, classe
CGopherFile, classe
CHttpConnection, classe