BOOL GetCookie(
	LPCTSTR lpszCookieName,
	LPTSTR lpszCookieValue,
	INT nCookieValue,
	LPTSTR lpszCookiePath,
	INT nCookiePath,
	LPTSTR lpszCookieDomain,
	INT nCookieDomain,
	LPSYSTEMTIME lpCookieExpires,
	LPDWORD lpdwCookieFlags
);

BOOL GetCookie(
	LPCTSTR lpszCookieName,
	CString& strCookieValue,
	CString& strCookiePath,
	CString& lpszCookieDomain,
	LPSYSTEMTIME lpCookieExpires,
	LPDWORD lpdwCookieFlags
);

BOOL GetCookie(
	LPCTSTR lpszCookieName,
	CString& strCookieValue
);

The GetCookie method returns information about a cookie set by the server.

Parameters

lpszCookieName

A pointer to a string which specifies the name of the cookie to return information about.

lpszCookieValue

A pointer to a string buffer that will contain the value of the cookie. If this information is not required, a NULL pointer may be specified.

nCookieValue

The maximum number of characters that may be copied into the buffer specified by the lpszCookieValue parameter, including the terminating null character.

lpszCookiePath

A pointer to a string buffer that will contain the cookie path. If this information is not required, a NULL pointer may be specified.

nCookiePath

The maximum number of characters that may be copied into the buffer specified by the lpszCookiePath parameter, including the terminating null character.

lpszCookieDomain

A pointer to a string buffer that will contain the cookie domain. If this information is not required, a NULL pointer may be specified.

nCookieDomain

The maximum number of characters that may be copied into the buffer specified by the lpszCookieDomain parameter, including the terminating null character.

lpCookieExpires

A pointer to a SYSTEMTIME structure which specifies the date and time that the cookie expires. If this information is not required, a NULL pointer may be specified.

lpdwCookieFlags

One or more bit flags which specify status information about the cookie. A value of zero indicates that there are no special status flags for the cookie. This parameter may be NULL if the information is not required. The following values are currently defined:

Constant	Description
HTTP_COOKIE_SECURE	This flag specifies that the cookie should only be provided to the server if the connection is secure.
HTTP_COOKIE_SESSION	This flag specifies that the cookie should only be used for the current application session and should not be stored permanently on the local system.

Return Value

If the method succeeds, the return value is non-zero. If the specified cookie does not exist or method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The Hypertext Transfer Protocol uses special tokens called "cookies" to maintain persistent state information between requests for a resource. These cookies are exchanged between the client and server by setting specific header fields. When a server wants the client to use a cookie, it will include a header field named Set-Cookie in the response header when the client requests a resource. The client can then take this cookie and store it, either temporarily in memory or permanently in a file on the local system. The next time that the client requests a resource from that server, it can send the cookie back to the server by setting the Cookie header field. The GetCookie method searches for a cookie set by the server in the Set-Cookie header field. The SetCookie method creates or modifies the Cookie header field for the next resource requested by the client.

There are two general types of cookies that are used by servers. Session cookies exist only for the duration of the client session; they are stored in memory and not saved in any kind of permanent storage. When the client application terminates, session cookies are deleted and no longer used. Persistent cookies are stored on the local system and are used by the client until their expiration time. It is the responsibility of the client application to store persistent cookies; applications may use a flat text file, a database or any other storage method available.

In addition to the cookie name and value, the server may return additional information about the cookie which the client should use to determine if it should send the cookie back to the server:

The cookie path specifies a path for the resources where the cookie should be used. For example, a path of "/" indicates that the cookie should be provided for all resources requested from the server. A path of "/data" would mean that the cookie should be included if the resource is found in the /data folder or a sub-folder, such as /data/projections.asp. However, the cookie would not be provided if the resource /info/status.asp was requested, since it is not in the /data path.

The cookie domain specifies the domain for which the cookie should be used. Matches are made by comparing the name of the server against the domain name specified in the cookie. If the domain is example.com, then any server in the example.com domain would match; for example, both shipping.example.com and orders.example.com would match the domain value. However, if the cookie domain was orders.example.com, then the cookie would only be sent if the resource was requested from orders.example.com, not if the resource was located on shipping.example.com or www.example.com.

The cookie expiration specifies the date and time that the cookie should be deleted and no longer sent when a resource is requested from the server. This is only valid for persistent cookies, since session cookies are automatically deleted when the client application terminates. The time is always expressed as Coordinated Universal Time.

The cookie flags provide additional information about the cookie. In some cases, a cookie should only be submitted to the server if the resource is requested using a secure connection. In this case, the bit flag HTTP_COOKIE_SECURE will be set.

It is the responsibility of the client application to determine if a cookie meets the criteria required to be submitted to the server. If the application wishes to send the cookie, it can use the SetCookie method and specify the cookie name and value.

Requirements

Minimum Desktop Platform: Windows 7 (Service Pack 1)
Minimum Server Platform: Windows Server 2008 R2 (Service Pack 1)
Header File: cstools10.h
Import Library: cshtpv10.lib

See Also

GetFirstCookie, GetNextCookie, GetHeader, SetCookie, SetHeader

Copyright © 2023 Catalyst Development Corporation. All rights reserved.