1 /* Interface for NSHTTPCookie for GNUstep 2 Copyright (C) 2006 Software Foundation, Inc. 3 4 Written by: Richard Frith-Macdonald <frm@gnu.org> 5 Date: 2006 6 7 This file is part of the GNUstep Base Library. 8 9 This library is free software; you can redistribute it and/or 10 modify it under the terms of the GNU Lesser General Public 11 License as published by the Free Software Foundation; either 12 version 2 of the License, or (at your option) any later version. 13 14 This library is distributed in the hope that it will be useful, 15 but WITHOUT ANY WARRANTY; without even the implied warranty of 16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 17 Lesser General Public License for more details. 18 19 You should have received a copy of the GNU Lesser General Public 20 License along with this library; if not, write to the Free 21 Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 22 Boston, MA 02110 USA. 23 */ 24 25 #ifndef __NSHTTPCookie_h_GNUSTEP_BASE_INCLUDE 26 #define __NSHTTPCookie_h_GNUSTEP_BASE_INCLUDE 27 #import <GNUstepBase/GSVersionMacros.h> 28 29 #if OS_API_VERSION(MAC_OS_X_VERSION_10_2,GS_API_LATEST) && GS_API_VERSION( 11300,GS_API_LATEST) 30 31 #import <Foundation/NSObject.h> 32 33 #if defined(__cplusplus) 34 extern "C" { 35 #endif 36 37 @class NSArray; 38 @class NSDate; 39 @class NSDictionary; 40 @class NSString; 41 @class NSURL; 42 43 extern NSString * const NSHTTPCookieComment; /** Obtain text of the comment */ 44 extern NSString * const NSHTTPCookieCommentURL; /** Obtain the comment URL */ 45 extern NSString * const NSHTTPCookieDiscard; /** Obtain the sessions discard setting */ 46 extern NSString * const NSHTTPCookieDomain; /** Obtain cookie domain */ 47 extern NSString * const NSHTTPCookieExpires; /** Obtain cookie expiry date */ 48 extern NSString * const NSHTTPCookieMaximumAge; /** Obtain maximum age (expiry) */ 49 extern NSString * const NSHTTPCookieName; /** Obtain name of cookie */ 50 extern NSString * const NSHTTPCookieOriginURL; /** Obtain cookie origin URL */ 51 extern NSString * const NSHTTPCookiePath; /** Obtain cookie path */ 52 extern NSString * const NSHTTPCookiePort; /** Obtain cookie ports */ 53 extern NSString * const NSHTTPCookieSecure; /** Obtain cookie security */ 54 extern NSString * const NSHTTPCookieValue; /** Obtain value of cookie */ 55 extern NSString * const NSHTTPCookieVersion; /** Obtain cookie version */ 56 57 58 /** 59 * An instance of the NSHTTPCookie class is a single, immutable http cookie. 60 * It can be initialised with properties from a dictionary and has accessor 61 * methods to obtain the cookie values.<br /> 62 * The class supports unversioned cookies (sometimes referred to as version 0) 63 * as originally produced by netscape, as well as more recent standardised 64 * and versioned cookies. 65 */ 66 @interface NSHTTPCookie : NSObject 67 { 68 #if GS_EXPOSE(NSHTTPCookie) 69 @private 70 void *_NSHTTPCookieInternal; 71 #endif 72 } 73 74 /** 75 * Allocates and returns an autoreleasd instance using -initWithProperties: 76 * to initialise it from properties. 77 */ 78 + (id) cookieWithProperties: (NSDictionary *)properties; 79 80 /** 81 * Returns an array of cookies parsed from the headerFields and URL 82 * (assuming that the headerFields came from a response to a request 83 * sent to the URL).<br /> 84 * The headerFields dictionary must contain at least all the headers 85 * relevant to cookie setting ... other headers are ignored. 86 */ 87 + (NSArray *) cookiesWithResponseHeaderFields: (NSDictionary *)headerFields 88 forURL: (NSURL *)URL; 89 90 /** 91 * Returns a dictionary of header fields that can be used to add the 92 * specified cookies to a request. 93 */ 94 + (NSDictionary *) requestHeaderFieldsWithCookies: (NSArray *)cookies; 95 96 /** 97 * Returns a string which may be used to describe the cookie to the 98 * user, or nil if no comment is set. 99 */ 100 - (NSString *) comment; 101 102 /** 103 * Returns a URL where the user can find out about the cookie, or nil 104 * if no comment URL is set. 105 */ 106 - (NSURL *) commentURL; 107 108 /** 109 * Returns the domain to which the cookie should be sent.<br /> 110 * If there is a leading dot then subdomains should also receive the 111 * cookie as specified in RFC 2965. 112 */ 113 - (NSString *) domain; 114 115 /** 116 * Returns the expiry date of the receiver or nil if there is no 117 * such date. 118 */ 119 - (NSDate *) expiresDate; 120 121 /** <init /> 122 * Initialises the receiver with a dictionary of properties.<br /> 123 * Unrecognised keys are ignored.<br /> 124 * Returns nil if a required key is missing or if an illegal 125 * value is specified for a key. 126 * <deflist> 127 * <term>NSHTTPCookieComment</term> 128 * <desc> 129 * The [NSString] comment for the cookie (if any).<br /> 130 * This is nil by default and for unversioned cookies. 131 * </desc> 132 * <term>NSHTTPCookieCommentURL</term> 133 * <desc> 134 * The [NSString] or [NSURL] URL to get the comment for the cookie.<br /> 135 * This is nil by default and for unversioned cookies. 136 * </desc> 137 * <term>NSHTTPCookieDomain</term> 138 * <desc> 139 * The [NSString] specified the domain to which the cookie applies.<br /> 140 * This is extracted from NSHTTPCookieOriginURL if not specified. 141 * </desc> 142 * <term>NSHTTPCookieDiscard</term> 143 * <desc> 144 * A [NSString] (either TRUE or FALSE) saying whether the cookie 145 * is to be discarded when the session ends.<br /> 146 * Defaults to FALSE except for versioned cookies where 147 * NSHTTPCookieMaximumAge is unspecified. 148 * </desc> 149 * <term>NSHTTPCookieExpires</term> 150 * <desc> 151 * The [NSDate] or [NSString] (format Wdy, DD-Mon-YYYY HH:MM:SS GMT) 152 * specifying when an unversioned cookie expires and ignored for 153 * versioned cookies. 154 * </desc> 155 * <term>NSHTTPCookieMaximumAge</term> 156 * <desc> 157 * An [NSString] containing an integer value specifying the longest time 158 * (in seconds) for which the cookie is valid.<br /> 159 * This defaults to zero and is only meaningful for versioned cookies. 160 * </desc> 161 * <term>NSHTTPCookieName</term> 162 * <desc> 163 * An [NSString] ... obvious ... no default value. 164 * </desc> 165 * <term>NSHTTPCookieOriginURL</term> 166 * <desc> 167 * An [NSString] or [NSURL] specifying the URL which set the cookie.<br /> 168 * Must be supplied if NSHTTPCookieDomain is not. 169 * </desc> 170 * <term>NSHTTPCookiePath</term> 171 * <desc> 172 * An [NSString] specifying the path from the cookie.<br /> 173 * If unspecified this value is determined from NSHTTPCookieOriginURL 174 * or defaults to '/'. 175 * </desc> 176 * <term>NSHTTPCookiePort</term> 177 * <desc> 178 * An [NSString] containing a comma separated list of integer port 179 * numbers. This is valid for versioned cookies and defaults to 180 * an empty string. 181 * </desc> 182 * <term>NSHTTPCookieSecure</term> 183 * <desc> 184 * An [NSString] saying whether the cookie may be sent over 185 * insecure connections.<br /> 186 * The default is FALSE meaning that it may be sent insecurely. 187 * </desc> 188 * <term>NSHTTPCookieValue</term> 189 * <desc> 190 * An [NSString] containing the whole value of the cooke.<br /> 191 * This parameter <strong>must</strong> be provided. 192 * </desc> 193 * <term>NSHTTPCookieVersion</term> 194 * <desc> 195 * An [NSString] specifying the cookie version ... for an 196 * unversioned cookie (the default) this is '0'.<br /> 197 * Also supports version '1'. 198 * </desc> 199 * </deflist> 200 */ 201 - (id) initWithProperties: (NSDictionary *)properties; 202 203 /** 204 * Returns whether the receiver should only be sent over 205 * secure connections. 206 */ 207 #if GS_HAS_DECLARED_PROPERTIES 208 @property (readonly, getter=isSecure) BOOL secure; 209 #else 210 - (BOOL) isSecure; 211 #endif 212 213 /** 214 * Returns whether the receiver should be destroyed at the end of the 215 * session. 216 */ 217 #if GS_HAS_DECLARED_PROPERTIES 218 @property (readonly, getter=isSessionOnly) BOOL sessionOnly; 219 #else 220 - (BOOL) isSessionOnly; 221 #endif 222 223 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6,GS_API_LATEST) 224 #if GS_HAS_DECLARED_PROPERTIES 225 @property (readonly, getter=isHTTPOnly) BOOL HTTPOnly; 226 #else 227 - (BOOL) isHTTPOnly; 228 #endif 229 #endif 230 231 /** 232 * Returns the name of the receiver. 233 */ 234 - (NSString *) name; 235 236 /** 237 * Returns the URL path within the cookie's domain for which 238 * this cookie must be sent. 239 */ 240 - (NSString *) path; 241 242 /** 243 * Returns the list of ports to which the receiver should be sent, 244 * or nil if the cookie can be used for any port. 245 */ 246 - (NSArray *) portList; 247 248 /** 249 * Returns a dictionary representation of the receiver which could be 250 * used as the argument for -initWithProperties: to recreate a copy 251 * of the receiver. 252 */ 253 - (NSDictionary *) properties; 254 255 /** 256 * Returns the value of the receiver. 257 */ 258 - (NSString *) value; 259 260 /** 261 * Returns 0 for an unversioned Netscape style cookie or a 262 * positive integer for a versioned cookie. 263 */ 264 - (NSUInteger) version; 265 266 @end 267 268 #if defined(__cplusplus) 269 } 270 #endif 271 272 #endif /* 100200 */ 273 274 #endif /* __NSHTTPCookie_h_GNUSTEP_BASE_INCLUDE */ 275