Struct NSURLConnection

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

Available on crate feature NSURLConnection only.

An NSURLConnection object provides support to perform asynchronous loads of a URL request, providing data to a client supplied delegate.

The interface for NSURLConnection is very sparse, providing only the controls to start and cancel asynchronous loads of a URL request.

An NSURLConnection may be used for loading of resource data directly to memory, in which case an NSURLConnectionDataDelegate should be supplied, or for downloading of resource data directly to a file, in which case an NSURLConnectionDownloadDelegate is used. The delegate is retained by the NSURLConnection until a terminal condition is encountered. These two delegates are logically subclasses of the base protocol, NSURLConnectionDelegate.

A terminal condition produced by the loader will result in a connection:didFailWithError: in the case of an error, or connectionDidFinishLoading: or connectionDidFinishDownloading: delegate message.

The -cancel message hints to the loader that a resource load should be abandoned but does not guarantee that more delegate messages will not be delivered. If -cancel does cause the load to be abandoned, the delegate will be released without further messages. In general, a caller should be prepared for -cancel to have no effect, and internally ignore any delegate callbacks until the delegate is released.

Scheduling of an NSURLConnection specifies the context in which delegate callbacks will be made, but the actual IO may occur on a separate thread and should be considered an implementation detail.

When created, an NSURLConnection performs a deep-copy of the NSURLRequest. This copy is available through the -originalRequest method. As the connection performs the load, this request may change as a result of protocol canonicalization or due to following redirects. -currentRequest can be used to retrieve this value.

An NSURLConnections created with the +connectionWithRequest:delegate: or -initWithRequest:delegate: methods are scheduled on the current runloop immediately, and it is not necessary to send the -start message to begin the resource load.

NSURLConnections created with -initWithRequest:delegate:startImmediately: are not automatically scheduled. Use -scheduleWithRunLoop:forMode: or -setDelegateQueue: to specify the context for delegate callbacks, and -start to begin the load. If you do not explicitly schedule the connection before -start, it will be scheduled on the current runloop and mode automatically.

The NSURLConnectionSynchronousLoading category adds +sendSynchronousRequest:returningResponse:error, which blocks the current thread until the resource data is available or an error occurs. It should be noted that using this method on an applications main run loop may result in an unacceptably long delay in a user interface and its use is strongly discourage.

The NSURLConnectionQueuedLoading category implements +sendAsynchronousRequest:queue:completionHandler, providing similar simplicity but provides a mechanism where the current runloop is not blocked.

Both of the immediate loading categories do not provide for customization of resource load, and do not allow the caller to respond to, e.g., authentication challenges.

See also Apple’s documentation

Implementations

impl NSURLConnection

pub unsafe fn initWithRequest_delegate_startImmediately( this: Allocated<Self>, request: &NSURLRequest, delegate: Option<&AnyObject>, start_immediately: bool, ) -> Option<Retained<Self>>

👎Deprecated: Use NSURLSession (see NSURLSession.h)

Available on crate feature NSURLRequest only.

pub unsafe fn initWithRequest_delegate( this: Allocated<Self>, request: &NSURLRequest, delegate: Option<&AnyObject>, ) -> Option<Retained<Self>>

👎Deprecated: Use NSURLSession (see NSURLSession.h)

Available on crate feature NSURLRequest only.

pub unsafe fn connectionWithRequest_delegate( request: &NSURLRequest, delegate: Option<&AnyObject>, ) -> Option<Retained<NSURLConnection>>

👎Deprecated: Use NSURLSession (see NSURLSession.h)

Available on crate feature NSURLRequest only.

pub unsafe fn originalRequest(&self) -> Retained<NSURLRequest>

Available on crate feature NSURLRequest only.

pub unsafe fn currentRequest(&self) -> Retained<NSURLRequest>

Available on crate feature NSURLRequest only.

pub unsafe fn start(&self)

pub unsafe fn cancel(&self)

pub unsafe fn scheduleInRunLoop_forMode( &self, a_run_loop: &NSRunLoop, mode: &NSRunLoopMode, )

Available on crate features NSObjCRuntime and NSRunLoop and NSString only.

pub unsafe fn unscheduleFromRunLoop_forMode( &self, a_run_loop: &NSRunLoop, mode: &NSRunLoopMode, )

Available on crate features NSObjCRuntime and NSRunLoop and NSString only.

pub unsafe fn setDelegateQueue(&self, queue: Option<&NSOperationQueue>)

Available on crate feature NSOperation only.

pub unsafe fn canHandleRequest(request: &NSURLRequest) -> bool

Available on crate feature NSURLRequest only.

Performs a “preflight” operation that performs some speculative checks to see if a connection can be initialized, and the associated I/O that is started in the initializer methods can begin.

The result of this method is valid only as long as no protocols are registered or unregistered, and as long as the request is not mutated (if the request is mutable). Hence, clients should be prepared to handle failures even if they have performed request preflighting by calling this method.

Parameter request: The request to preflight.

Returns: YES if it is likely that the given request can be used to initialize a connection and the associated I/O can be started, NO otherwise.

impl NSURLConnection

Methods declared on superclass NSObject.

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

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

impl NSURLConnection

NSURLConnectionSynchronousLoading. The NSURLConnectionSynchronousLoading category on NSURLConnection provides the interface to perform synchronous loading of URL requests.

pub unsafe fn sendSynchronousRequest_returningResponse_error( request: &NSURLRequest, response: Option<&mut Option<Retained<NSURLResponse>>>, ) -> Result<Retained<NSData>, Retained<NSError>>

👎Deprecated: Use [NSURLSession dataTaskWithRequest:completionHandler:] (see NSURLSession.h

Available on crate features NSData and NSError and NSURLRequest and NSURLResponse only.

Performs a synchronous load of the given request, returning an NSURLResponse in the given out parameter.

A synchronous load for the given request is built on top of the asynchronous loading code made available by the class. The calling thread is blocked while the asynchronous loading system performs the URL load on a thread spawned specifically for this load request. No special threading or run loop configuration is necessary in the calling thread in order to perform a synchronous load. For instance, the calling thread need not be running its run loop.

Parameter request: The request to load. Note that the request is deep-copied as part of the initialization process. Changes made to the request argument after this method returns do not affect the request that is used for the loading process.

Parameter response: An out parameter which is filled in with the response generated by performing the load.

Parameter error: Out parameter (may be NULL) used if an error occurs while processing the request. Will not be modified if the load succeeds.

Returns: The content of the URL resulting from performing the load, or nil if the load failed.

impl NSURLConnection

NSURLConnectionQueuedLoading. The NSURLConnectionQueuedLoading category on NSURLConnection provides the interface to perform asynchronous loading of URL requests where the results of the request are delivered to a block via an NSOperationQueue.

Note that there is no guarantee of load ordering implied by this method.

pub unsafe fn sendAsynchronousRequest_queue_completionHandler( request: &NSURLRequest, queue: &NSOperationQueue, handler: &DynBlock<dyn Fn(*mut NSURLResponse, *mut NSData, *mut NSError)>, )

👎Deprecated: Use [NSURLSession dataTaskWithRequest:completionHandler:] (see NSURLSession.h

Available on crate features NSData and NSError and NSOperation and NSURLRequest and NSURLResponse and block2 only.

Performs an asynchronous load of the given request. When the request has completed or failed, the block will be executed from the context of the specified NSOperationQueue.

This is a convenience routine that allows for asynchronous loading of a url-based resource. If the resource load is successful, the data parameter to the callback will contain the resource data and the error parameter will be nil. If the resource load fails, the data parameter will be nil and the error will contain information about the failure.

Parameter request: The request to load. Note that the request is deep-copied as part of the initialization process. Changes made to the request argument after this method returns do not affect the request that is used for the loading process.

Parameter queue: An NSOperationQueue upon which the handler block will be dispatched.

Parameter handler: A block which receives the results of the resource load.

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 NSURLConnection

fn as_ref(&self) -> &AnyObject

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

impl AsRef<NSObject> for NSURLConnection

fn as_ref(&self) -> &NSObject

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

impl AsRef<NSURLConnection> for NSURLConnection

fn as_ref(&self) -> &Self

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

impl Borrow<AnyObject> for NSURLConnection

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for NSURLConnection

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for NSURLConnection

const NAME: &'static str = "NSURLConnection"

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

type Super = NSObject

The superclass of this class.

type ThreadKind = <<NSURLConnection 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 NSURLConnection

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

Formats the value using the given formatter.

impl Deref for NSURLConnection

type Target = NSObject

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for NSURLConnection

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 NSURLConnection

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

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for NSURLConnection

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 NSURLConnection

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 NSURLConnection

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

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

impl DowncastTarget for NSURLConnection

impl Eq for NSURLConnection