Struct NWTCPConnection

Source

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

👎Deprecated: Use nw_connection_t in Network framework instead, see deprecation notice in <NetworkExtension/NWTCPConnection.h>

Expand description

Establish TCP connections to an endpoint, and send and receive data on the TCP connection.

Implementations§

Source §

impl NWTCPConnection

Source

pub unsafe fn initWithUpgradeForConnection( this: Allocated<Self>, connection: &NWTCPConnection, ) -> Retained<Self>

👎Deprecated: Use nw_connection_create in Network framework instead, see deprecation notice in <NetworkExtension/NWTCPConnection.h>

This convenience initializer can be used to create a new connection that would only be connected if there exists a better path (as determined by the system) to the destination endpoint of the original connection. It will be initialized using the same destination endpoint and set of parameters from the original connection.

If the original connection becomes disconnected or cancelled, the new “upgrade” connection would automatically be considered better.

The caller should create an NWTCPConnection and watch for the hasBetterPath property. When this property is YES, the caller should attempt to create a new upgrade connection, with the goal to start transferring data on the new better path as soon as possible to reduce power and potentially monetary cost. When the new upgrade connection becomes connected and when the caller wraps up the previous caller session on the original connection, the caller can start using the new upgrade connection and tear down the original one.

Parameter connection: The original connection from which the caller will upgrade

Returns: An initialized NWTCPConnection

Source

pub unsafe fn state(&self) -> NWTCPConnectionState

👎Deprecated: Use nw_connection_set_state_changed_handler in Network framework instead, see deprecation notice in <NetworkExtension/NWTCPConnection.h>

The status of the connection. Use KVO to watch this property to get updates.

Source

pub unsafe fn isViable(&self) -> bool

👎Deprecated: Use nw_connection_set_viability_changed_handler in Network framework instead, see deprecation notice in <NetworkExtension/NWTCPConnection.h>

YES if the connection can read and write data, NO otherwise. Use KVO to watch this property.

Source

pub unsafe fn hasBetterPath(&self) -> bool

👎Deprecated: Use nw_connection_set_better_path_available_handler in Network framework instead, see deprecation notice in <NetworkExtension/NWTCPConnection.h>

YES if the system determines there is a better path the destination can be reached if the caller creates a new connection using the same endpoint and parameters. This can be done using the convenience upgrade initializer method. Use KVO to watch this property to get updates.

Source

pub unsafe fn endpoint(&self) -> Retained<NWEndpoint>

👎Deprecated: Use nw_connection_copy_endpoint in Network framework instead, see deprecation notice in <NetworkExtension/NWTCPConnection.h>

The destination endpoint with which this connection was created.

Source

pub unsafe fn connectedPath(&self) -> Option<Retained<NWPath>>

👎Deprecated: Use nw_connection_copy_current_path in Network framework instead, see deprecation notice in <NetworkExtension/NWTCPConnection.h>

The network path over which the connection was established. The caller can query additional properties from the NWPath object for more information.

Note that this contains a snapshot of information at the time of connection establishment for this connection only. As a result, some underlying properties might change in time and might not reflect the path for other connections that might be established at different times.

Source

pub unsafe fn localAddress(&self) -> Option<Retained<NWEndpoint>>

👎Deprecated: Use nw_path_copy_effective_local_endpoint in Network framework instead, see deprecation notice in <NetworkExtension/NWTCPConnection.h>

The IP address endpoint from which the connection was connected.

Source

pub unsafe fn remoteAddress(&self) -> Option<Retained<NWEndpoint>>

👎Deprecated: Use nw_path_copy_effective_remote_endpoint in Network framework instead, see deprecation notice in <NetworkExtension/NWTCPConnection.h>

The IP address endpoint to which the connection was connected.

Source

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

👎Deprecated: Use nw_endpoint_copy_txt_record in Network framework instead, see deprecation notice in <NetworkExtension/NWTCPConnection.h>

When the connection is connected to a Bonjour service endpoint, the TXT record associated with the Bonjour service is available via this property. Beware that the value comes from the network. Care must be taken when parsing this potentially malicious value.

Source

pub unsafe fn error(&self) -> Option<Retained<NSError>>

👎Deprecated: Use nw_connection_set_state_changed_handler in Network framework instead, see deprecation notice in <NetworkExtension/NWTCPConnection.h>

The connection-wide error property indicates any fatal error that occurred while processing the connection or performing data reading or writing.

Source

pub unsafe fn cancel(&self)

👎Deprecated: Use nw_connection_cancel in Network framework instead, see deprecation notice in <NetworkExtension/NWTCPConnection.h>

Cancel the connection. This will clean up the resources associated with this object and transition this object to NWTCPConnectionStateCancelled state.

Source

pub unsafe fn readLength_completionHandler( &self, length: NSUInteger, completion: &DynBlock<dyn Fn(mut NSData, mut NSError)>, )

👎Deprecated: Use nw_connection_receive in Network framework instead, see deprecation notice in <NetworkExtension/NWTCPConnection.h>

Available on crate feature block2 only.

Read “length” number of bytes. See readMinimumLength:maximumLength:completionHandler: for a complete discussion of the callback behavior.

Parameter length: The exact number of bytes the application wants to read

Parameter completion: The completion handler to be invoked when there is data to read or an error occurred

Source

pub unsafe fn readMinimumLength_maximumLength_completionHandler( &self, minimum: NSUInteger, maximum: NSUInteger, completion: &DynBlock<dyn Fn(mut NSData, mut NSError)>, )

👎Deprecated: Use nw_connection_receive in Network framework instead, see deprecation notice in <NetworkExtension/NWTCPConnection.h>

Available on crate feature block2 only.

Read the requested range of bytes. The completion handler will be invoked when:

Exactly “length” number of bytes have been read. ‘data’ will be non-nil.
Fewer than “length” number of bytes, including 0 bytes, have been read, and the connection’s read side has been closed. ‘data’ might be nil, depending on whether there was any data to be read when the connection’s read side was closed.
Some fatal error has occurred, and ‘data’ will be nil.

To know when to schedule a read again, check for the condition whether an error has occurred.

For better performance, the caller should pick the effective minimum and maximum lengths. For example, if the caller absolutely needs a specific number of bytes before it can make any progress, use that value as the minimum. The maximum bytes can be the upperbound that the caller wants to read. Typically, the minimum length can be the caller protocol fixed-size header and the maximum length can be the maximum size of the payload or the size of the current read buffer.

Parameter minimum: The minimum number of bytes the caller wants to read

Parameter maximum: The maximum number of bytes the caller wants to read

Parameter completion: The completion handler to be invoked when there is data to read or an error occurred

Source

pub unsafe fn write_completionHandler( &self, data: &NSData, completion: &DynBlock<dyn Fn(*mut NSError)>, )

👎Deprecated: Use nw_connection_send in Network framework instead, see deprecation notice in <NetworkExtension/NWTCPConnection.h>

Available on crate feature block2 only.

Write the given data object content. Callers should wait until the completionHandler is executed before issuing another write.

Parameter data: The data object whose content will be written

Parameter completion: The completion handler to be invoked when the data content has been written or an error has occurred. If the error is nil, the write succeeded and the caller can write more data.

Source

pub unsafe fn writeClose(&self)

👎Deprecated: Use nw_connection_send in Network framework instead, see deprecation notice in <NetworkExtension/NWTCPConnection.h>

Close this connection’s write side such that further write requests won’t succeed. Note that this has the effect of closing the read side of the peer connection. When the connection’s read side and write side are closed, the connection is considered disconnected and will transition to the appropriate state.

Source §

impl NWTCPConnection

Methods declared on superclass NSObject.

Source

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

Source

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

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