Struct CWInterface

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

Available on crate feature CWInterface only.

Control and query a Wi-Fi interface on OS X.

All actions performed by a CWInterface object are executed on the Wi-Fi device with the corresponding interface name.

See also Apple’s documentation

Implementations

impl CWInterface

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

Returns the BSD name of the Wi-Fi interface (e.g. “en0”).

pub unsafe fn powerOn(&self) -> bool

Returns: YES if the Wi-Fi interface is on, NO otherwise.

Indicates the Wi-Fi interface power state.

Returns NO if an error occurs.

pub unsafe fn supportedWLANChannels(&self) -> Option<Retained<NSSet<CWChannel>>>

Available on crate feature CWChannel only.

Returns: An NSSet of CWChannel objects.

Returns the set of channels supported by the Wi-Fi interface for the currently adopted country code.

Returns nil if an error occurs.

pub unsafe fn wlanChannel(&self) -> Option<Retained<CWChannel>>

Available on crate feature CWChannel only.

Returns the current channel of the Wi-Fi interface.

Returns nil if an error occurs.

pub unsafe fn activePHYMode(&self) -> CWPHYMode

Available on crate feature CoreWLANTypes only.

Returns the currently active physical layer (PHY) mode of the Wi-Fi interface.

Returns kCWPHYModeNone if an error occurs.

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

Returns the current service set identifier (SSID) of the Wi-Fi interface, encoded as a string.

Returns nil if an error occurs, or if the interface is not participating in a Wi-Fi network, or if the SSID can not be encoded as a valid UTF-8 or WinLatin1 string.

Note: SSID information is not available unless Location Services is enabled and the user has authorized the calling app to use location services.

See also: CLLocationManager

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

Returns the current service set identifier (SSID) for the interface, encapsulated in an NSData object.

Returns nil if an error occurs, or if the interface is not participating in a Wi-Fi network.

Note: SSID information is not available unless Location Services is enabled and the user has authorized the calling app to use location services.

See also: CLLocationManager

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

Returns the current basic service set identifier (BSSID) of the Wi-Fi interface, returned as an UTF-8 string.

Returns a UTF-8 string using hexadecimal characters formatted as XX:XX:XX:XX:XX:XX. Returns nil if an error occurred, or if the interface is not participating in a Wi-Fi network.

Note: BSSID information is not available unless Location Services is enabled and the user has authorized the calling app to use location services.

See also: CLLocationManager

pub unsafe fn rssiValue(&self) -> NSInteger

Returns the current received signal strength indication (RSSI) measurement (dBm) for the Wi-Fi interface.

Returns 0 if an error occurs, or if the interface is not participating in a Wi-Fi network.

pub unsafe fn noiseMeasurement(&self) -> NSInteger

Returns the current noise measurement (dBm) for the Wi-Fi interface.

Returns 0 if an error occurs, or if the interface is not participating in a Wi-Fi network.

pub unsafe fn security(&self) -> CWSecurity

Available on crate feature CoreWLANTypes only.

Returns the current security type of the Wi-Fi interface.

Returns kCWSecurityUnknown if an error occurs, or if the interface is not participating in a Wi-Fi network.

pub unsafe fn transmitRate(&self) -> c_double

Returns the current transmit rate (Mbps) for the Wi-Fi interface.

Returns 0 if an error occurs, or if the interface is not participating in a Wi-Fi network.

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

Returns the currently adopted country code (ISO/IEC 3166-1:1997) for the Wi-Fi interface.

Returns nil if an error occurs, or if the Wi-Fi interface is off.

Note: Country code information is not available unless Location Services is enabled and the user has authorized the calling app to use location services.

See also: CLLocationManager

pub unsafe fn interfaceMode(&self) -> CWInterfaceMode

Available on crate feature CoreWLANTypes only.

Returns the current operating mode for the Wi-Fi interface.

Returns kCWInterfaceModeNone if an error occurs, or if the interface is not participating in a Wi-Fi network.

pub unsafe fn transmitPower(&self) -> NSInteger

Returns the current transmit power (mW) for the Wi-Fi interface.

Returns 0 if an error occurs.

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

Returns the hardware media access control (MAC) address for the Wi-Fi interface, returned as an UTF-8 string.

The standard format for printing a MAC-48 address XX:XX:XX:XX:XX:XX is used to represent the MAC address as a string. Returns nil if an error occurs.

pub unsafe fn serviceActive(&self) -> bool

Returns: YES if the corresponding network service is active, NO otherwise.

Indicates the network service state of the Wi-Fi interface.

Returns NO if an error occurs.

pub unsafe fn cachedScanResults(&self) -> Option<Retained<NSSet<CWNetwork>>>

Available on crate feature CWNetwork only.

Returns: An NSSet of CWNetwork objects.

Returns the scan results currently in the scan cache for the Wi-Fi interface.

Returns nil if an error occurs.

pub unsafe fn configuration(&self) -> Option<Retained<CWConfiguration>>

Available on crate feature CWConfiguration only.

Returns the current configuration for the Wi-Fi interface.

Returns nil if an error occurs.

pub unsafe fn interfaceNames() -> Option<Retained<NSSet<NSString>>>

👎Deprecated: Use -[CWWiFiClient interfaceNames] instead

Returns: An NSSet of NSString objects.

Returns the list of available Wi-Fi interface names (e.g. “en0”).

Returns an empty NSArray object if no Wi-Fi interfaces exist. Returns nil if an error occurs.

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

👎Deprecated: Use -[CWWiFiClient interface] instead

Convenience method for getting a CWInterface object for the default Wi-Fi interface.

pub unsafe fn interfaceWithName(name: Option<&NSString>) -> Retained<Self>

👎Deprecated: Use -[CWWiFiClient interfaceWithName:] instead

Parameter name: The name of an available Wi-Fi interface.

Convenience method for getting a CWInterface object bound to the Wi-Fi interface with a specific interface name.

Use +[CWInterface interfaceNames] to get a list of available Wi-Fi interface names. Returns a CWInterface object for the default Wi-Fi interface if no interface name is specified.

pub unsafe fn initWithInterfaceName( this: Allocated<Self>, name: Option<&NSString>, ) -> Retained<Self>

👎Deprecated: Use -[CWWiFiClient interfaceWithName:] instead

Parameter name: The name of an available Wi-Fi interface.

Initializes a CWInterface object, binding to the Wi-Fi interface with a specific interface name.

Use +[CWInterface interfaceNames] to get a list of available Wi-Fi interface names. Returns a CWInterface object for the default Wi-Fi interface if no interface name is specified.

pub unsafe fn setPower_error( &self, power: bool, ) -> Result<(), Retained<NSError>>

Parameter power: A BOOL value indicating Wi-Fi power state. Specify YES to turn on the Wi-Fi interface.

Parameter error: An NSError object passed by reference, which upon return will contain the error if an error occurs. This parameter is optional.

Returns: Returns YES upon success, or NO if an error occurred.

Sets the Wi-Fi interface power state.

pub unsafe fn setWLANChannel_error( &self, channel: &CWChannel, ) -> Result<(), Retained<NSError>>

Available on crate feature CWChannel only.

Parameter channel: A CWChannel object.

Parameter error: An NSError object passed by reference, which upon return will contain the error if an error occurs. This parameter is optional.

Returns: Returns YES upon success, or NO if an error occurred.

Sets the Wi-Fi interface channel.

Setting the channel while the interface is associated to a Wi-Fi network is not permitted.

pub unsafe fn setPairwiseMasterKey_error( &self, key: Option<&NSData>, ) -> Result<(), Retained<NSError>>

Parameter key: An NSData object containing the pairwise master key (PMK). Passing nil clear the PMK for the Wi-Fi interface.

Parameter error: An NSError object passed by reference, which upon return will contain the error if an error occurs. This parameter is optional.

Returns: Returns YES upon success, or NO if an error occurred.

Sets the Wi-Fi interface pairwise master key (PMK).

The specified key must be exactly 32 octets.

pub unsafe fn setWEPKey_flags_index_error( &self, key: Option<&NSData>, flags: CWCipherKeyFlags, index: NSInteger, ) -> Result<(), Retained<NSError>>

Available on crate feature CoreWLANTypes only.

Parameter key: An NSData object containing the WEP key. Passing nil clears the WEP key for the Wi-Fi interface.

Parameter flags: A bitmask indicating which CWCipherKeyFlags to use for the specified WEP key.

Parameter index: An NSInteger indicating which default key index (1-4) to use for the specified key.

Parameter error: An NSError object passed by reference, which upon return will contain the error if an error occurs. This parameter is optional.

Returns: Returns YES upon success, or NO if an error occurred.

Sets the Wi-Fi interface WEP key.

pub unsafe fn scanForNetworksWithSSID_error( &self, ssid: Option<&NSData>, ) -> Result<Retained<NSSet<CWNetwork>>, Retained<NSError>>

Available on crate feature CWNetwork only.

Parameter ssid: Probe request SSID. Pass an SSID to perform a directed scan for hidden Wi-Fi networks. This parameter is optional.

Parameter error: An NSError object passed by reference, which upon return will contain the error if an error occurs. This parameter is optional.

Returns: An NSSet of CWNetwork objects, or nil if an error occurs.

Performs a scan for Wi-Fi networks and returns scan results to the caller.

This method will block for the duration of the scan.

Note: Returned networks will not contain BSSID information unless Location Services is enabled and the user has authorized the calling app to use location services.

See also: CLLocationManager

pub unsafe fn scanForNetworksWithSSID_includeHidden_error( &self, ssid: Option<&NSData>, include_hidden: bool, ) -> Result<Retained<NSSet<CWNetwork>>, Retained<NSError>>

Available on crate feature CWNetwork only.

Parameter ssid: Probe request SSID. Pass an SSID to perform a directed scan for hidden Wi-Fi networks. This parameter is optional.

Parameter includeHidden: Indicate whether or not hidden networks should not be filtered from the returned scan results.

Parameter error: An NSError object passed by reference, which upon return will contain the error if an error occurs. This parameter is optional.

Returns: An NSSet of CWNetwork objects, or nil if an error occurs.

Performs a scan for Wi-Fi networks and returns scan results to the caller.

This method will block for the duration of the scan.

Note: Returned networks will not contain BSSID information unless Location Services is enabled and the user has authorized the calling app to use location services.

See also: CLLocationManager

pub unsafe fn scanForNetworksWithName_error( &self, network_name: Option<&NSString>, ) -> Result<Retained<NSSet<CWNetwork>>, Retained<NSError>>

Available on crate feature CWNetwork only.

Parameter networkName: Probe request SSID, encoded as an UTF-8 string. Pass a networkName to perform a directed scan for hidden Wi-Fi networks. This parameter is optional.

Parameter error: An NSError object passed by reference, which upon return will contain the error if an error occurs. This parameter is optional.

Returns: An NSSet of CWNetwork objects, or nil if an error occurs.

Performs a scan for Wi-Fi networks and returns scan results to the caller.

This method will block for the duration of the scan.

Note: Returned networks will not contain BSSID information unless Location Services is enabled and the user has authorized the calling app to use location services.

See also: CLLocationManager

pub unsafe fn scanForNetworksWithName_includeHidden_error( &self, network_name: Option<&NSString>, include_hidden: bool, ) -> Result<Retained<NSSet<CWNetwork>>, Retained<NSError>>

Available on crate feature CWNetwork only.

Parameter networkName: Probe request SSID, encoded as an UTF-8 string. Pass a networkName to perform a directed scan for hidden Wi-Fi networks. This parameter is optional.

Parameter includeHidden: Indicate whether or not hidden networks should not be filtered from the returned scan results.

Parameter error: An NSError object passed by reference, which upon return will contain the error if an error occurs. This parameter is optional.

Returns: An NSSet of CWNetwork objects, or nil if an error occurs.

Performs a scan for Wi-Fi networks and returns scan results to the caller.

This method will block for the duration of the scan.

Note: Returned networks will not contain BSSID information unless Location Services is enabled and the user has authorized the calling app to use location services.

See also: CLLocationManager

pub unsafe fn associateToNetwork_password_error( &self, network: &CWNetwork, password: Option<&NSString>, ) -> Result<(), Retained<NSError>>

Available on crate feature CWNetwork only.

Parameter network: The network to which the Wi-Fi interface will associate.

Parameter password: The network passphrase or key. Required for association to WEP, WPA Personal, and WPA2 Personal networks.

Parameter error: An NSError object passed by reference, which upon return will contain the error if an error occurs. This parameter is optional.

Returns: Returns YES upon success, or NO if an error occurred.

Associates to a W-Fi network using the specified passphrase.

This method will block for the duration of the association.

pub unsafe fn disassociate(&self)

Disassociates from the current Wi-Fi network.

pub unsafe fn associateToEnterpriseNetwork_identity_username_password_error( &self, network: &CWNetwork, identity: Option<&SecIdentity>, username: Option<&NSString>, password: Option<&NSString>, ) -> Result<(), Retained<NSError>>

Available on crate features CWNetwork and objc2-security only.

Parameter network: The network to which the Wi-Fi interface will associate.

Parameter username: The username to use for 802.1X authentication.

Parameter password: The password to use for 802.1X authentication.

Parameter identity: The identity to use for IEEE 802.1X authentication. Holds the corresponding client certificate.

Parameter error: An NSError object passed by reference, which upon return will contain the error if an error occurs. This parameter is optional.

Returns: Returns YES upon success, or NO if an error occurred.

Associates to an enterprise W-Fi network using the specified 802.1X credentials.

This method will block for the duration of the association.

pub unsafe fn startIBSSModeWithSSID_security_channel_password_error( &self, ssid_data: &NSData, security: CWIBSSModeSecurity, channel: NSUInteger, password: Option<&NSString>, ) -> Result<(), Retained<NSError>>

👎Deprecated

Available on crate feature CoreWLANTypes only.

Parameter ssidData: The SSID to use for the IBSS network. Pass nil to use the machine name as the IBSS network name.

Parameter security: The CWIBSSModeSecurity type.

Parameter channel: The channel on which the IBSS network will be created.

Parameter password: The password to be used. This paramter is required for kCWIBSSModeSecurityWEP40 or kCWIBSSModeSecurityWEP104 security types.

Parameter error: An NSError object passed by reference, which upon return will contain the error if an error occurs. This parameter is optional.

Returns: Returns YES upon success, or NO if an error occurred.

Creates a computer-to-computer (IBSS) network.

impl CWInterface

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 CWInterface

fn as_ref(&self) -> &AnyObject

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

impl AsRef<CWInterface> for CWInterface

fn as_ref(&self) -> &Self

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

impl AsRef<NSObject> for CWInterface

fn as_ref(&self) -> &NSObject

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

impl Borrow<AnyObject> for CWInterface

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for CWInterface

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for CWInterface

const NAME: &'static str = "CWInterface"

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

type Super = NSObject

The superclass of this class.

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

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

Formats the value using the given formatter.

impl Deref for CWInterface

type Target = NSObject

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for CWInterface

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 CWInterface

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

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for CWInterface

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 CWInterface

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 CWInterface

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

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

impl DowncastTarget for CWInterface

impl Eq for CWInterface