Struct NSHTTPCookie

#[repr(C)]
pub struct NSHTTPCookie { /* private fields */ }

Available on crate feature NSHTTPCookie only.

NSHTTPCookie represents an http cookie.

A NSHTTPCookie instance represents a single http cookie. It is an immutable object initialized from a dictionary that contains the various cookie attributes. It has accessors to get the various attributes of a cookie.

See also Apple’s documentation

Implementations

impl NSHTTPCookie

pub unsafe fn initWithProperties( this: Allocated<Self>, properties: &NSDictionary<NSHTTPCookiePropertyKey, AnyObject>, ) -> Option<Retained<Self>>

Available on crate features NSDictionary and NSString only.

Initialize a NSHTTPCookie object with a dictionary of parameters

Parameter properties: The dictionary of properties to be used to initialize this cookie.

Supported dictionary keys and value types for the given dictionary are as follows.

All properties can handle an NSString value, but some can also handle other types.

Property key constant	Type of value	Required	Description
NSHTTPCookieComment	NSString	NO	Comment for the cookie. Only valid for version 1 cookies and later. Default is nil.
NSHTTPCookieCommentURL	NSURL or NSString	NO	Comment URL for the cookie. Only valid for version 1 cookies and later. Default is nil.
NSHTTPCookieDomain	NSString	Special, a value for either NSHTTPCookieOriginURL or NSHTTPCookieDomain must be specified.	Domain for the cookie. Inferred from the value for NSHTTPCookieOriginURL if not provided.
NSHTTPCookieDiscard	NSString	NO	A string stating whether the cookie should be discarded at the end of the session. String value must be either "TRUE" or "FALSE". Default is "FALSE", unless this is cookie is version 1 or greater and a value for NSHTTPCookieMaximumAge is not specified, in which case it is assumed "TRUE".
NSHTTPCookieExpires	NSDate or NSString	NO	Expiration date for the cookie. Used only for version 0 cookies. Ignored for version 1 or greater.
NSHTTPCookieMaximumAge	NSString	NO	A string containing an integer value stating how long in seconds the cookie should be kept, at most. Only valid for version 1 cookies and later. Default is "0".
NSHTTPCookieName	NSString	YES	Name of the cookie
NSHTTPCookieOriginURL	NSURL or NSString	Special, a value for either NSHTTPCookieOriginURL or NSHTTPCookieDomain must be specified.	URL that set this cookie. Used as default for other fields as noted.
NSHTTPCookiePath	NSString	NO	Path for the cookie. Inferred from the value for NSHTTPCookieOriginURL if not provided. Default is "/".
NSHTTPCookiePort	NSString	NO	comma-separated integer values specifying the ports for the cookie. Only valid for version 1 cookies and later. Default is empty string ("").
NSHTTPCookieSecure	NSString	NO	A string stating whether the cookie should be transmitted only over secure channels. String value must be either "TRUE" or "FALSE". Default is "FALSE".
NSHTTPCookieValue	NSString	YES	Value of the cookie
NSHTTPCookieVersion	NSString	NO	Specifies the version of the cookie. Must be either "0" or "1". Default is "0".
NSHTTPCookieSetByJavaScript	NSNumber	NO	`true`if the cookie is set via JavaScript. `false`if the cookie is not set via JavaScript

All other keys are ignored.

Returns: An initialized NSHTTPCookie, or nil if the set of dictionary keys is invalid, for example because a required key is missing, or a recognized key maps to an illegal value.

pub unsafe fn cookieWithProperties( properties: &NSDictionary<NSHTTPCookiePropertyKey, AnyObject>, ) -> Option<Retained<NSHTTPCookie>>

Available on crate features NSDictionary and NSString only.

Allocates and initializes an NSHTTPCookie with the given dictionary.

See the NSHTTPCookie -initWithProperties: method for more information on the constraints imposed on the dictionary, and for descriptions of the supported keys and values.

Parameter properties: The dictionary to use to initialize this cookie.

Returns: A newly-created and autoreleased NSHTTPCookie instance, or nil if the set of dictionary keys is invalid, for example because a required key is missing, or a recognized key maps to an illegal value.

pub unsafe fn requestHeaderFieldsWithCookies( cookies: &NSArray<NSHTTPCookie>, ) -> Retained<NSDictionary<NSString, NSString>>

Available on crate features NSArray and NSDictionary and NSString only.

Return a dictionary of header fields that can be used to add the specified cookies to the request.

Parameter cookies: The cookies to turn into request headers.

Returns: An NSDictionary where the keys are header field names, and the values are the corresponding header field values.

pub unsafe fn cookiesWithResponseHeaderFields_forURL( header_fields: &NSDictionary<NSString, NSString>, url: &NSURL, ) -> Retained<NSArray<NSHTTPCookie>>

Available on crate features NSArray and NSDictionary and NSString and NSURL only.

Return an array of cookies parsed from the specified response header fields and URL.

Parameter headerFields: The response header fields to check for cookies.

Parameter URL: The URL that the cookies came from - relevant to how the cookies are interpreted.

Returns: An NSArray of NSHTTPCookie objects

This method will ignore irrelevant header fields so you can pass a dictionary containing data other than cookie data.

pub unsafe fn properties( &self, ) -> Option<Retained<NSDictionary<NSHTTPCookiePropertyKey, AnyObject>>>

Available on crate features NSDictionary and NSString only.

Returns a dictionary representation of the receiver.

This method returns a dictionary representation of the NSHTTPCookie which can be saved and passed to -initWithProperties: or +cookieWithProperties: later to reconstitute an equivalent cookie.

See the NSHTTPCookie -initWithProperties: method for more information on the constraints imposed on the dictionary, and for descriptions of the supported keys and values.

Returns: The dictionary representation of the receiver.

pub unsafe fn version(&self) -> NSUInteger

Returns the version of the receiver.

Version 0 maps to “old-style” Netscape cookies. Version 1 maps to RFC2965 cookies. There may be future versions.

Returns: the version of the receiver.

pub unsafe fn name(&self) -> Retained<NSString>

Available on crate feature NSString only.

Returns the name of the receiver.

Returns: the name of the receiver.

pub unsafe fn value(&self) -> Retained<NSString>

Available on crate feature NSString only.

Returns the value of the receiver.

Returns: the value of the receiver.

pub unsafe fn expiresDate(&self) -> Option<Retained<NSDate>>

Available on crate feature NSDate only.

Returns the expires date of the receiver.

Returns: the expires date of the receiver.

The expires date is the date when the cookie should be deleted. The result will be nil if there is no specific expires date. This will be the case only for “session-only” cookies.

Returns: The expires date of the receiver.

pub unsafe fn isSessionOnly(&self) -> bool

Returns whether the receiver is session-only.

Returns: YES if this receiver should be discarded at the end of the session (regardless of expiration date), NO if receiver need not be discarded at the end of the session.

pub unsafe fn domain(&self) -> Retained<NSString>

Available on crate feature NSString only.

Returns the domain of the receiver.

This value specifies URL domain to which the cookie should be sent. A domain with a leading dot means the cookie should be sent to subdomains as well, assuming certain other restrictions are valid. See RFC 2965 for more detail.

Returns: The domain of the receiver.

pub unsafe fn path(&self) -> Retained<NSString>

Available on crate feature NSString only.

Returns the path of the receiver.

This value specifies the URL path under the cookie’s domain for which this cookie should be sent. The cookie will also be sent for children of that path, so “/” is the most general.

Returns: The path of the receiver.

pub unsafe fn isSecure(&self) -> bool

Returns whether the receiver should be sent only over secure channels

Cookies may be marked secure by a server (or by a javascript). Cookies marked as such must only be sent via an encrypted connection to trusted servers (i.e. via SSL or TLS), and should not be delivered to any javascript applications to prevent cross-site scripting vulnerabilities.

Returns: YES if this cookie should be sent only over secure channels, NO otherwise.

pub unsafe fn isHTTPOnly(&self) -> bool

Returns whether the receiver should only be sent to HTTP servers per RFC 2965

Cookies may be marked as HTTPOnly by a server (or by a javascript). Cookies marked as such must only be sent via HTTP Headers in HTTP Requests for URL’s that match both the path and domain of the respective Cookies. Specifically these cookies should not be delivered to any javascript applications to prevent cross-site scripting vulnerabilities.

Returns: YES if this cookie should only be sent via HTTP headers, NO otherwise.

pub unsafe fn comment(&self) -> Option<Retained<NSString>>

Available on crate feature NSString only.

Returns the comment of the receiver.

This value specifies a string which is suitable for presentation to the user explaining the contents and purpose of this cookie. It may be nil.

Returns: The comment of the receiver, or nil if the receiver has no comment.

pub unsafe fn commentURL(&self) -> Option<Retained<NSURL>>

Available on crate feature NSURL only.

Returns the comment URL of the receiver.

This value specifies a URL which is suitable for presentation to the user as a link for further information about this cookie. It may be nil.

Returns: The comment URL of the receiver, or nil if the receiver has no comment URL.

pub unsafe fn portList(&self) -> Option<Retained<NSArray<NSNumber>>>

Available on crate features NSArray and NSValue only.

Returns the list ports to which the receiver should be sent.

This value specifies an NSArray of NSNumbers (containing integers) which specify the only ports to which this cookie should be sent.

Returns: The list ports to which the receiver should be sent. The array may be nil, in which case this cookie can be sent to any port.

pub unsafe fn sameSitePolicy( &self, ) -> Option<Retained<NSHTTPCookieStringPolicy>>

Available on crate feature NSString only.

Returns the value of the same site attribute on the cookie.

Cookies can be marked with an attribute Strict or Lax. Cookies marked with “strict” (NSHTTPCookieSameSiteStrict) are not sent along with cross-site requests. Cookies marked with “lax” (NSHTTPCookieSameSiteLax) sent along cross-site requests provided the cross-site requests are top-level-requests (one that changes the url in the address bar). The attribute value is canonicalized and stored. Any value other than the default (strict and lax) will be ignored.

Returns: strict or lax. The result could also be nil, in which case the cookie will be sent along with all cross-site requests.

impl NSHTTPCookie

Methods declared on superclass NSObject.

pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>

pub unsafe fn new() -> Retained<Self>

Methods from Deref<Target = NSObject>

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>

pub fn class(&self) -> &'static AnyClass

Dynamically find the class of this object.

Panics

May panic if the object is invalid (which may be the case for objects returned from unavailable init/new methods).

Example

Check that an instance of NSObject has the precise class NSObject.

use objc2::ClassType;
use objc2::runtime::NSObject;

let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());

pub unsafe fn get_ivar<T>(&self, name: &str) -> &T

where T: Encode,

👎Deprecated: this is difficult to use correctly, use Ivar::load instead.

Use Ivar::load instead.

Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: DowncastTarget,

Attempt to downcast the object to a class of type T.

This is the reference-variant. Use Retained::downcast if you want to convert a retained object to another type.

Mutable classes

Some classes have immutable and mutable variants, such as NSString and NSMutableString.

When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.

So using this method to convert a NSString to a NSMutableString, while not unsound, is generally frowned upon unless you created the string yourself, or the API explicitly documents the string to be mutable.

See Apple’s documentation on mutability and on isKindOfClass: for more details.

Generic classes

Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.

You can, however, safely downcast to generic collections where all the type-parameters are AnyObject.

Panics

This works internally by calling isKindOfClass:. That means that the object must have the instance method of that name, and an exception will be thrown (if CoreFoundation is linked) or the process will abort if that is not the case. In the vast majority of cases, you don’t need to worry about this, since both root objects NSObject and NSProxy implement this method.

Examples

Cast an NSString back and forth from NSObject.

use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};

let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();

Try (and fail) to cast an NSObject to an NSString.

use objc2_foundation::{NSObject, NSString};

let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());

Try to cast to an array of strings.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();

This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.

Downcast when processing each element instead.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);

for elem in arr {
    if let Some(data) = elem.downcast_ref::<NSString>() {
        // handle `data`
    }
}

Trait Implementations

impl AsRef<AnyObject> for NSHTTPCookie

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSHTTPCookie> for NSHTTPCookie

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSObject> for NSHTTPCookie

fn as_ref(&self) -> &NSObject

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AnyObject> for NSHTTPCookie

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for NSHTTPCookie

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for NSHTTPCookie

const NAME: &'static str = "NSHTTPCookie"

The name of the Objective-C class that this type represents.

type Super = NSObject

The superclass of this class.

type ThreadKind = <<NSHTTPCookie as ClassType>::Super as ClassType>::ThreadKind

Whether the type can be used from any thread, or from only the main thread.

fn class() -> &'static AnyClass

Get a reference to the Objective-C class that this type represents.

fn as_super(&self) -> &Self::Super

Get an immutable reference to the superclass.

impl Debug for NSHTTPCookie

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for NSHTTPCookie

type Target = NSObject

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for NSHTTPCookie

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for NSHTTPCookie

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for NSHTTPCookie

fn isEqual(&self, other: Option<&AnyObject>) -> bool

where Self: Sized + Message,

Check whether the object is equal to an arbitrary other object.

fn hash(&self) -> usize

where Self: Sized + Message,

An integer that can be used as a table address in a hash table structure.

fn isKindOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of the class, or one of its subclasses.

fn is_kind_of<T>(&self) -> bool

where T: ClassType, Self: Sized + Message,

👎Deprecated: use isKindOfClass directly, or cast your objects with AnyObject::downcast_ref

Check if the object is an instance of the class type, or one of its subclasses.

fn isMemberOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of a specific class, without checking subclasses.

fn respondsToSelector(&self, aSelector: Sel) -> bool

where Self: Sized + Message,

Check whether the object implements or inherits a method with the given selector.

fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool

where Self: Sized + Message,

Check whether the object conforms to a given protocol.

fn description(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object.

fn debugDescription(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object to use when debugging.

fn isProxy(&self) -> bool

where Self: Sized + Message,

Check whether the receiver is a subclass of the NSProxy root class instead of the usual NSObject.

fn retainCount(&self) -> usize

where Self: Sized + Message,

The reference count of the object.

impl PartialEq for NSHTTPCookie

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for NSHTTPCookie

const ENCODING_REF: Encoding = <NSObject as ::objc2::RefEncode>::ENCODING_REF

The Objective-C type-encoding for a reference of this type.

impl DowncastTarget for NSHTTPCookie

impl Eq for NSHTTPCookie

impl Send for NSHTTPCookie

impl Sync for NSHTTPCookie