Struct NSURLProtocol

Source

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

Available on crate feature NSURLProtocol only.

Expand description

NSURLProtocol is an abstract class which provides the basic structure for performing protocol-specific loading of URL data. Concrete subclasses handle the specifics associated with one or more protocols or URL schemes.

Implementations§

Source §

impl NSURLProtocol

Source

pub unsafe fn initWithRequest_cachedResponse_client( this: Allocated<Self>, request: &NSURLRequest, cached_response: Option<&NSCachedURLResponse>, client: Option<&ProtocolObject<dyn NSURLProtocolClient>>, ) -> Retained<Self>

Available on crate features NSURLCache and NSURLRequest only.

Initializes an NSURLProtocol given request, cached response, and client.

Parameter request: The request to load.

Parameter cachedResponse: A response that has been retrieved from the cache for the given request. The protocol implementation should apply protocol-specific validity checks if such tests are necessary.

Parameter client: The NSURLProtocolClient object that serves as the interface the protocol implementation can use to report results back to the URL loading system.

Source

pub unsafe fn client( &self, ) -> Option<Retained<ProtocolObject<dyn NSURLProtocolClient>>>

Returns the NSURLProtocolClient of the receiver.

Returns: The NSURLProtocolClient of the receiver.

Source

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

Available on crate feature NSURLRequest only.

Returns the NSURLRequest of the receiver.

Returns: The NSURLRequest of the receiver.

Source

pub unsafe fn cachedResponse(&self) -> Option<Retained<NSCachedURLResponse>>

Available on crate feature NSURLCache only.

Returns the NSCachedURLResponse of the receiver.

Returns: The NSCachedURLResponse of the receiver.

Source

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

Available on crate feature NSURLRequest only.

This method determines whether this protocol can handle the given request.

A concrete subclass should inspect the given request and determine whether or not the implementation can perform a load with that request. This is an abstract method. Subclasses must provide an implementation.

Parameter request: A request to inspect.

Returns: YES if the protocol can handle the given request, NO if not.

Source

pub unsafe fn canonicalRequestForRequest( request: &NSURLRequest, ) -> Retained<NSURLRequest>

Available on crate feature NSURLRequest only.

This method returns a canonical version of the given request.

It is up to each concrete protocol implementation to define what “canonical” means. However, a protocol should guarantee that the same input request always yields the same canonical form. Special consideration should be given when implementing this method since the canonical form of a request is used to look up objects in the URL cache, a process which performs equality checks between NSURLRequest objects.

This is an abstract method; subclasses must provide an implementation.

Parameter request: A request to make canonical.

Returns: The canonical form of the given request.

Source

pub unsafe fn requestIsCacheEquivalent_toRequest( a: &NSURLRequest, b: &NSURLRequest, ) -> bool

Available on crate feature NSURLRequest only.

Compares two requests for equivalence with regard to caching.

Requests are considered equivalent for cache purposes if and only if they would be handled by the same protocol AND that protocol declares them equivalent after performing implementation-specific checks.

Returns: YES if the two requests are cache-equivalent, NO otherwise.

Source

pub unsafe fn startLoading(&self)

Starts protocol-specific loading of a request.

When this method is called, the protocol implementation should start loading a request.

Source

pub unsafe fn stopLoading(&self)

Stops protocol-specific loading of a request.

When this method is called, the protocol implementation should end the work of loading a request. This could be in response to a cancel operation, so protocol implementations must be able to handle this call while a load is in progress.

Source

pub unsafe fn propertyForKey_inRequest( key: &NSString, request: &NSURLRequest, ) -> Option<Retained<AnyObject>>

Available on crate features NSString and NSURLRequest only.

Returns the property in the given request previously stored with the given key.

The purpose of this method is to provide an interface for protocol implementors to access protocol-specific information associated with NSURLRequest objects.

Parameter key: The string to use for the property lookup.

Parameter request: The request to use for the property lookup.

Returns: The property stored with the given key, or nil if no property had previously been stored with the given key in the given request.

Source

pub unsafe fn setProperty_forKey_inRequest( value: &AnyObject, key: &NSString, request: &NSMutableURLRequest, )

Available on crate features NSString and NSURLRequest only.

Stores the given property in the given request using the given key.

The purpose of this method is to provide an interface for protocol implementors to customize protocol-specific information associated with NSMutableURLRequest objects.

Parameter value: The property to store.

Parameter key: The string to use for the property storage.

Parameter request: The request in which to store the property.

Source

pub unsafe fn removePropertyForKey_inRequest( key: &NSString, request: &NSMutableURLRequest, )

Available on crate features NSString and NSURLRequest only.

Remove any property stored under the given key

Like setProperty:forKey:inRequest: above, the purpose of this method is to give protocol implementors the ability to store protocol-specific information in an NSURLRequest

Parameter key: The key whose value should be removed

Parameter request: The request to be modified

Source

pub unsafe fn registerClass(protocol_class: &AnyClass) -> bool

This method registers a protocol class, making it visible to several other NSURLProtocol class methods.

When the URL loading system begins to load a request, each protocol class that has been registered is consulted in turn to see if it can be initialized with a given request. The first protocol handler class to provide a YES answer to +canInitWithRequest: “wins” and that protocol implementation is used to perform the URL load. There is no guarantee that all registered protocol classes will be consulted. Hence, it should be noted that registering a class places it first on the list of classes that will be consulted in calls to +canInitWithRequest: , moving it in front of all classes that had been registered previously.

A similar design governs the process to create the canonical form of a request with the +canonicalRequestForRequest: class method.

Parameter protocolClass: the class to register.

Returns: YES if the protocol was registered successfully, NO if not. The only way that failure can occur is if the given class is not a subclass of NSURLProtocol.

Source

pub unsafe fn unregisterClass(protocol_class: &AnyClass)

This method unregisters a protocol.

After unregistration, a protocol class is no longer consulted in calls to NSURLProtocol class methods.

Parameter protocolClass: The class to unregister.

Source §

impl NSURLProtocol

Methods declared on superclass NSObject.

Source

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

Source

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

Source §

impl NSURLProtocol

NSURLSessionTaskAdditions.

Source

pub unsafe fn canInitWithTask(task: &NSURLSessionTask) -> bool

Available on crate feature NSURLSession only.

Source

pub unsafe fn initWithTask_cachedResponse_client( this: Allocated<Self>, task: &NSURLSessionTask, cached_response: Option<&NSCachedURLResponse>, client: Option<&ProtocolObject<dyn NSURLProtocolClient>>, ) -> Retained<Self>

Available on crate features NSURLCache and NSURLSession only.

Source

pub unsafe fn task(&self) -> Option<Retained<NSURLSessionTask>>

Available on crate feature NSURLSession only.

Methods from Deref<Target = NSObject>§

Source

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

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>§

Source

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());

Source

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.

Source

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`
    }
}