CHttpFile, classe
Fournit les fonctionnalités permettant de demander et de lire des fichiers sur un serveur HTTP.
class CHttpFile : public CInternetFile
Nom | Description |
---|---|
CHttpFile ::CHttpFile | Crée un objet CHttpFile . |
Nom | Description |
---|---|
CHttpFile ::AddRequestHeaders | Ajoute des en-têtes à la requête envoyée à un serveur HTTP. |
CHttpFile ::EndRequest | Termine une requête envoyée à un serveur HTTP avec la fonction membre SendRequestEx . |
CHttpFile ::GetFileURL | Obtient l’URL du fichier spécifié. |
CHttpFile ::GetObject | Obtient l’objet cible du verbe dans une requête adressée à un serveur HTTP. |
CHttpFile ::GetVerb | Obtient le verbe utilisé dans une requête adressée à un serveur HTTP. |
CHttpFile ::QueryInfo | Retourne les en-têtes de réponse ou de requête du serveur HTTP. |
CHttpFile ::QueryInfoStatusCode | Récupère le code d’état associé à une requête HTTP et le place dans le paramètre fourni dwStatusCode . |
CHttpFile ::SendRequest | Envoie une requête à un serveur HTTP. |
CHttpFile ::SendRequestEx | Envoie une requête à un serveur HTTP à l’aide des méthodes Write ou WriteString de CInternetFile . |
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.
CHttpFile
En-tête : afxinet.h
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);
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 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.
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.
Notes
L’application peut passer plusieurs en-têtes dans pstrHeaders ou str pour un AddRequestHeaders
appel à l’aide de HTTP_ADDREQ_FLAG_ADD ou de HTTP_ADDREQ_FLAG_ADD_IF_NEW. Si l’application tente de supprimer ou de remplacer un en-tête à l’aide de HTTP_ADDREQ_FLAG_REMOVE ou de HTTP_ADDREQ_FLAG_REPLACE, un seul en-tête peut être fourni dans lpszHeaders.
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);
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 .
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 .
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);
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 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.
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 .
Appelez cette fonction membre pour obtenir le nom du fichier HTTP en tant qu’URL.
virtual CString GetFileURL() const;
Objet CString contenant une URL référençant la ressource associée à ce fichier.
Utilisez cette fonction membre uniquement après un appel réussi à SendRequest ou sur un CHttpFile
objet créé avec succès par OpenURL.
Appelez cette fonction membre pour obtenir le nom de l’objet associé à ce CHttpFile
.
CString GetObject() const;
Objet CString contenant le nom de l’objet.
Utilisez cette fonction membre uniquement après un appel réussi à SendRequest ou sur un CHttpFile
objet créé avec succès par OpenURL.
Appelez cette fonction membre pour obtenir le verbe HTTP (ou méthode) associé à ce CHttpFile
.
CString GetVerb() const;
Objet CString contenant le nom du verbe HTTP (ou méthode).
Utilisez cette fonction membre uniquement après un appel réussi à SendRequest ou sur un CHttpFile
objet créé avec succès par OpenURL.
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;
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 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.
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
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;
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 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.
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.
Groupe | Signification |
---|---|
200-299 | Opération réussie |
300-399 | Information |
400-499 | Erreur de requête |
500-599 | Erreur serveur |
Codes d’état HTTP courants :
Code d’état | Signification |
---|---|
200 | URL située, transmission suivante |
400 | Requête inintelligible |
404 | URL demandée introuvable |
405 | Le serveur ne prend pas en charge la méthode demandée |
500 | Erreur de serveur inconnue |
503 | Capacité du serveur atteinte |
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);
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 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.
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);
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.
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.
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 .
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, WriteString
l’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();
CInternetFile, classe
Graphique hiérarchique
CInternetFile, classe
CGopherFile, classe
CHttpConnection, classe