InternetGetCookieExA function (wininet.h)

  • Article

The InternetGetCookieEx function retrieves data stored in cookies associated with a specified URL. Unlike InternetGetCookie, InternetGetCookieEx can be used to restrict data retrieved to a single cookie name or, by policy, associated with untrusted sites or third-party cookies.

Syntax

BOOL InternetGetCookieExA(
  [in]                LPCSTR  lpszUrl,
  [in]                LPCSTR  lpszCookieName,
  [in, out, optional] LPSTR   lpszCookieData,
  [in, out]           LPDWORD lpdwSize,
  [in]                DWORD   dwFlags,
  [in]                LPVOID  lpReserved
);

Parameters

[in] lpszUrl

A pointer to a null-terminated string that contains the URL with which the cookie to retrieve is associated. This parameter cannot be NULL or InternetGetCookieEx fails and returns an ERROR_INVALID_PARAMETER error.

[in] lpszCookieName

A pointer to a null-terminated string that contains the name of the cookie to retrieve. This name is case-sensitive.

[in, out, optional] lpszCookieData

A pointer to a buffer to receive the cookie data.

[in, out] lpdwSize

A pointer to a DWORD variable.

On entry, the variable must contain the size, in TCHARs, of the buffer pointed to by the pchCookieData parameter.

On exit, if the function is successful, this variable contains the number of TCHARs of cookie data copied into the buffer. If NULL was passed as the lpszCookieData parameter, or if the function fails with an error of ERROR_INSUFFICIENT_BUFFER, the variable contains the size, in BYTEs, of buffer required to receive the cookie data.

This parameter cannot be NULL or InternetGetCookieEx fails and returns an ERROR_INVALID_PARAMETER error.

[in] dwFlags

A flag that controls how the function retrieves cookie data. This parameter can be one of the following values.

Value Meaning
INTERNET_COOKIE_HTTPONLY
 Enables the retrieval of cookies that are marked as "HTTPOnly".

Do not use this flag if you expose a scriptable interface, because this has security implications. It is imperative that you use this flag only if you can guarantee that you will never expose the cookie to third-party code by way of an extensibility mechanism you provide.

Version:  Requires Internet Explorer 8.0 or later.
INTERNET_COOKIE_THIRD_PARTY
 Retrieves only third-party cookies if policy explicitly allows all cookies for the specified URL to be retrieved.
INTERNET_FLAG_RESTRICTED_ZONE
 Retrieves only cookies that would be allowed if the specified URL were untrusted; that is, if it belonged to the URLZONE_UNTRUSTED zone.

[in] lpReserved

Reserved for future use. Set to NULL.

Return value

If the function succeeds, the function returns TRUE.

If the function fails, it returns FALSE. To get a specific error value, call GetLastError.

If NULL is passed to lpszCookieData, the call will succeed and the function will not set ERROR_INSUFFICIENT_BUFFER.

The following error codes may be set by this function.

Return code Description
ERROR_INSUFFICIENT_BUFFER
 Returned if cookie data retrieved is larger than the buffer size pointed to by the pcchCookieData parameter or if that parameter is NULL.
ERROR_INVALID_PARAMETER
 Returned if either the pchURL or the pcchCookieData parameter is NULL.
ERROR_NO_MORE_ITEMS
 Returned if no cookied data as specified could be retrieved.

Remarks

Note  WinINet does not support server implementations. In addition, it should not be used from a service. For server implementations or services use Microsoft Windows HTTP Services (WinHTTP).
 

Note

The wininet.h header defines InternetGetCookieEx as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header wininet.h
Library Wininet.lib
DLL Wininet.dll

See also

HTTP Cookies

InternetGetCookie

InternetSetCookie

InternetSetCookieEx

Managing Cookies

WinINet Functions