Struct NSURLRequest

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

Available on crate feature NSURLRequest only.

An NSURLRequest object represents a URL load request in a manner independent of protocol and URL scheme.

NSURLRequest encapsulates two basic data elements about a URL load request:

• The URL to load.
• The policy to use when consulting the URL content cache made available by the implementation.

In addition, NSURLRequest is designed to be extended to support protocol-specific data by adding categories to access a property object provided in an interface targeted at protocol implementors.

• Protocol implementors should direct their attention to the NSURLRequestExtensibility category on NSURLRequest for more information on how to provide extensions on NSURLRequest to support protocol-specific request information.
• Clients of this API who wish to create NSURLRequest objects to load URL content should consult the protocol-specific NSURLRequest categories that are available. The NSHTTPURLRequest category on NSURLRequest is an example.

Objects of this class are used to create NSURLConnection instances, which can are used to perform the load of a URL, or as input to the NSURLConnection class method which performs synchronous loads.

See also Apple’s documentation

Implementations

impl NSURLRequest

pub unsafe fn requestWithURL(url: &NSURL) -> Retained<Self>

Available on crate feature NSURL only.

Allocates and initializes an NSURLRequest with the given URL.

Default values are used for cache policy (NSURLRequestUseProtocolCachePolicy) and timeout interval (60 seconds).

Parameter URL: The URL for the request.

Returns: A newly-created and autoreleased NSURLRequest instance.

pub unsafe fn supportsSecureCoding() -> bool

Indicates that NSURLRequest implements the NSSecureCoding protocol.

Returns: A BOOL value set to YES.

pub unsafe fn requestWithURL_cachePolicy_timeoutInterval( url: &NSURL, cache_policy: NSURLRequestCachePolicy, timeout_interval: NSTimeInterval, ) -> Retained<Self>

Available on crate features NSDate and NSURL only.

Allocates and initializes a NSURLRequest with the given URL and cache policy.

Parameter URL: The URL for the request.

Parameter cachePolicy: The cache policy for the request.

Parameter timeoutInterval: The timeout interval for the request. See the commentary for the timeoutInterval for more information on timeout intervals.

Returns: A newly-created and autoreleased NSURLRequest instance.

pub unsafe fn initWithURL(this: Allocated<Self>, url: &NSURL) -> Retained<Self>

Available on crate feature NSURL only.

Initializes an NSURLRequest with the given URL.

Default values are used for cache policy (NSURLRequestUseProtocolCachePolicy) and timeout interval (60 seconds).

Parameter URL: The URL for the request.

Returns: An initialized NSURLRequest.

pub unsafe fn initWithURL_cachePolicy_timeoutInterval( this: Allocated<Self>, url: &NSURL, cache_policy: NSURLRequestCachePolicy, timeout_interval: NSTimeInterval, ) -> Retained<Self>

Available on crate features NSDate and NSURL only.

Initializes an NSURLRequest with the given URL and cache policy.

This is the designated initializer for the NSURLRequest class.

Parameter URL: The URL for the request.

Parameter cachePolicy: The cache policy for the request.

Parameter timeoutInterval: The timeout interval for the request. See the commentary for the timeoutInterval for more information on timeout intervals.

Returns: An initialized NSURLRequest.

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

Available on crate feature NSURL only.

Returns the URL of the receiver.

Returns: The URL of the receiver.

pub unsafe fn cachePolicy(&self) -> NSURLRequestCachePolicy

Returns the cache policy of the receiver.

Returns: The cache policy of the receiver.

pub unsafe fn timeoutInterval(&self) -> NSTimeInterval

Available on crate feature NSDate only.

Returns the timeout interval of the receiver.

The timeout interval specifies the limit on the idle interval allotted to a request in the process of loading. The “idle interval” is defined as the period of time that has passed since the last instance of load activity occurred for a request that is in the process of loading. Hence, when an instance of load activity occurs (e.g. bytes are received from the network for a request), the idle interval for a request is reset to 0. If the idle interval ever becomes greater than or equal to the timeout interval, the request is considered to have timed out. This timeout interval is measured in seconds.

Returns: The timeout interval of the receiver.

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

Available on crate feature NSURL only.

The main document URL associated with this load.

This URL is used for the cookie “same domain as main document” policy, and attributing the request as a sub-resource of a user-specified URL. There may also be other future uses. See setMainDocumentURL:

Returns: The main document URL.

pub unsafe fn networkServiceType(&self) -> NSURLRequestNetworkServiceType

Returns the NSURLRequestNetworkServiceType associated with this request.

This will return NSURLNetworkServiceTypeDefault for requests that have not explicitly set a networkServiceType (using the setNetworkServiceType method).

Returns: The NSURLRequestNetworkServiceType associated with this request.

pub unsafe fn allowsCellularAccess(&self) -> bool

returns whether a connection created with this request is allowed to use the built in cellular radios (if present).

Returns: YES if the receiver is allowed to use the built in cellular radios to satisfy the request, NO otherwise.

pub unsafe fn allowsExpensiveNetworkAccess(&self) -> bool

returns whether a connection created with this request is allowed to use network interfaces which have been marked as expensive.

Returns: YES if the receiver is allowed to use an interface marked as expensive to satisfy the request, NO otherwise.

pub unsafe fn allowsConstrainedNetworkAccess(&self) -> bool

returns whether a connection created with this request is allowed to use network interfaces which have been marked as constrained.

Returns: YES if the receiver is allowed to use an interface marked as constrained to satisfy the request, NO otherwise.

pub unsafe fn assumesHTTP3Capable(&self) -> bool

returns whether we assume that server supports HTTP/3. Enables QUIC racing without HTTP/3 service discovery.

Returns: YES if server endpoint is known to support HTTP/3. Defaults to NO. The default may be YES in a future OS update.

pub unsafe fn attribution(&self) -> NSURLRequestAttribution

Returns the NSURLRequestAttribution associated with this request.

This will return NSURLRequestAttributionDeveloper for requests that have not explicitly set an attribution.

Returns: The NSURLRequestAttribution associated with this request.

pub unsafe fn requiresDNSSECValidation(&self) -> bool

sets whether a request is required to do DNSSEC validation during DNS lookup.

YES, if the DNS lookup for this request should require DNSSEC validation, No otherwise. Defaults to NO.

pub unsafe fn allowsPersistentDNS(&self) -> bool

Allows storing and usage of DNS answers, potentially beyond TTL expiry, in a persistent per-process cache. This should only be set for hostnames whose resolutions are not expected to change across networks.

YES, if the DNS lookup for this request is allowed to use a persistent per-process cache, NO otherwise. Defaults to NO.

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

Available on crate feature NSString only.

impl NSURLRequest

Methods declared on superclass NSObject.

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

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

impl NSURLRequest

NSHTTPURLRequest. The NSHTTPURLRequest on NSURLRequest provides methods for accessing information specific to HTTP protocol requests.

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

Available on crate feature NSString only.

Returns the HTTP request method of the receiver.

Returns: the HTTP request method of the receiver.

pub unsafe fn allHTTPHeaderFields( &self, ) -> Option<Retained<NSDictionary<NSString, NSString>>>

Available on crate features NSDictionary and NSString only.

Returns a dictionary containing all the HTTP header fields of the receiver.

Returns: a dictionary containing all the HTTP header fields of the receiver.

pub unsafe fn valueForHTTPHeaderField( &self, field: &NSString, ) -> Option<Retained<NSString>>

Available on crate feature NSString only.

Returns the value which corresponds to the given header field. Note that, in keeping with the HTTP RFC, HTTP header field names are case-insensitive.

Parameter field: the header field name to use for the lookup (case-insensitive).

Returns: the value associated with the given header field, or nil if there is no value associated with the given header field.

pub unsafe fn HTTPBody(&self) -> Option<Retained<NSData>>

Available on crate feature NSData only.

Returns the request body data of the receiver.

This data is sent as the message body of the request, as in done in an HTTP POST request.

Returns: The request body data of the receiver.

pub unsafe fn HTTPBodyStream(&self) -> Option<Retained<NSInputStream>>

Available on crate feature NSStream only.

Returns the request body stream of the receiver if any has been set

The stream is returned for examination only; it is not safe for the caller to manipulate the stream in any way. Also note that the HTTPBodyStream and HTTPBody are mutually exclusive - only one can be set on a given request. Also note that the body stream is preserved across copies, but is LOST when the request is coded via the NSCoding protocol

Returns: The request body stream of the receiver.

pub unsafe fn HTTPShouldHandleCookies(&self) -> bool

Determine whether default cookie handling will happen for this request.

NOTE: This value is not used prior to 10.3

Returns: YES if cookies will be sent with and set for this request; otherwise NO.

pub unsafe fn HTTPShouldUsePipelining(&self) -> bool

👎Deprecated: Only supported in the classic loader, please adopt HTTP/2 and HTTP/3 instead

Reports whether the receiver is not expected to wait for the previous response before transmitting.

Returns: YES if the receiver should transmit before the previous response is received. NO if the receiver should wait for the previous response before transmitting.

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 NSURLRequest

fn as_ref(&self) -> &AnyObject

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

impl AsRef<NSObject> for NSURLRequest

fn as_ref(&self) -> &NSObject

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

impl AsRef<NSURLRequest> for NSMutableURLRequest

fn as_ref(&self) -> &NSURLRequest

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

impl AsRef<NSURLRequest> for NSURLRequest

fn as_ref(&self) -> &Self

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

impl Borrow<AnyObject> for NSURLRequest

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for NSURLRequest

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl Borrow<NSURLRequest> for NSMutableURLRequest

fn borrow(&self) -> &NSURLRequest

Immutably borrows from an owned value.

impl ClassType for NSURLRequest

const NAME: &'static str = "NSURLRequest"

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

type Super = NSObject

The superclass of this class.

type ThreadKind = <<NSURLRequest 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 CopyingHelper for NSURLRequest

Available on crate feature NSObject only.

type Result = NSURLRequest

The immutable counterpart of the type, or Self if the type has no immutable counterpart.

impl Debug for NSURLRequest

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

Formats the value using the given formatter.

impl Deref for NSURLRequest

type Target = NSObject

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for NSURLRequest

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 NSURLRequest

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

where Self: Sized,

Increment the reference count of the receiver.

impl MutableCopyingHelper for NSURLRequest

Available on crate feature NSObject only.

type Result = NSMutableURLRequest

The mutable counterpart of the type, or Self if the type has no mutable counterpart.

impl NSCoding for NSURLRequest

unsafe fn encodeWithCoder(&self, coder: &NSCoder)

where Self: Sized + Message,

Available on crate features NSObject and NSCoder only.

unsafe fn initWithCoder( this: Allocated<Self>, coder: &NSCoder, ) -> Option<Retained<Self>>

where Self: Sized + Message,

Available on crate features NSObject and NSCoder only.

impl NSCopying for NSURLRequest

fn copy(&self) -> Retained<Self::Result>

where Self: Sized + Message + CopyingHelper,

Available on crate feature NSObject only.

Returns a new instance that’s a copy of the receiver.

unsafe fn copyWithZone(&self, zone: *mut NSZone) -> Retained<Self::Result>

where Self: Sized + Message + CopyingHelper,

Available on crate feature NSObject only.

Returns a new instance that’s a copy of the receiver.

impl NSMutableCopying for NSURLRequest

fn mutableCopy(&self) -> Retained<Self::Result>

where Self: Sized + Message + MutableCopyingHelper,

Available on crate feature NSObject only.

Returns a new instance that’s a mutable copy of the receiver.

unsafe fn mutableCopyWithZone( &self, zone: *mut NSZone, ) -> Retained<Self::Result>

where Self: Sized + Message + MutableCopyingHelper,

Available on crate feature NSObject only.

Returns a new instance that’s a mutable copy of the receiver.

impl NSObjectProtocol for NSURLRequest

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 NSSecureCoding for NSURLRequest

unsafe fn supportsSecureCoding() -> bool

where Self: Sized + ClassType,

Available on crate feature NSObject only.

impl PartialEq for NSURLRequest

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 NSURLRequest

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

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

impl DowncastTarget for NSURLRequest

impl Eq for NSURLRequest