Struct SCNetworkConnection

Source

pub struct SCNetworkConnection { /* private fields */ }

Available on crate feature SCNetworkConnection only.

Expand description

This is the handle to manage a connection-oriented service.

Implementations§

Source §

impl SCNetworkConnection

Source

pub unsafe fn user_preferences( selection_options: Option<&CFDictionary>, service_id: NonNull<const CFString>, user_options: NonNull<const CFDictionary>, ) -> bool

Provides the default service ID and a dictionary of user options for the connection. Applications can use the returned serviceID and userOptions values to open a connection on the fly.

Parameter selectionOptions: Currently unimplemented. Pass NULL for this version.

Parameter serviceID: Reference to the default serviceID for starting connections, this value will be returned by the function.

Parameter userOptions: Reference to default userOptions for starting connections, this will be returned by the function.

Returns: Returns TRUE if there is a valid service to dial; FALSE if the function was unable to retrieve a service to dial.

§Safety

selection_options generics must be of the correct type.
service_id must be a valid pointer.
user_options must be a valid pointer.

Source

pub unsafe fn with_service_id( allocator: Option<&CFAllocator>, service_id: &CFString, callout: SCNetworkConnectionCallBack, context: *mut SCNetworkConnectionContext, ) -> Option<CFRetained<SCNetworkConnection>>

Creates a new connection reference to use for getting the status or for connecting or disconnecting the associated service.

Parameter allocator: The CFAllocator that should be used to allocate memory for the connection structure. This parameter may be NULL in which case the current default CFAllocator is used. If this reference is not a valid CFAllocator, the behavior is undefined.

Parameter serviceID: A string that defines the service identifier of the connection. Service identifiers uniquely identify services in the system configuration database.

Parameter callout: The function to be called when the status of the connection changes. If this parameter is NULL, the application will not receive notifications of status change and will need to poll for updates.

Parameter context: The SCNetworkConnectionContext associated with the callout.

Returns: Returns a reference to the new SCNetworkConnection.

§Safety

callout must be implemented correctly.
context must be a valid pointer or null.

Source

pub fn service_id(&self) -> Option<CFRetained<CFString>>

Returns the service ID associated with the SCNetworkConnection.

Parameter connection: The SCNetworkConnection to obtain status from.

Returns: Returns the service ID associated with the SCNetworkConnection.

Source

pub fn status(&self) -> SCNetworkConnectionStatus

Returns the status of the SCNetworkConnection. A status is one of the following values:


```text
 
    kSCNetworkConnectionInvalid
    kSCNetworkConnectionDisconnected
    kSCNetworkConnectionConnecting
    kSCNetworkConnectionDisconnecting
    kSCNetworkConnectionConnected
```

Parameter connection: The SCNetworkConnection to obtain status from.

Returns: Returns the status value.

Source

pub fn extended_status(&self) -> Option<CFRetained<CFDictionary>>

Returns the extended status of the connection. An extended status dictionary contains specific dictionaries describing the status for each subcomponent of the service.

For example, a status dictionary will contain the following sub-dictionaries, keys, and values:


```text
 
    IPv4  : Addresses      : the assigned IP address.
 
    PPP   : Status         : the PPP-specific status of type
                 SCNetworkConnectionPPPStatus.
 
        LastCause      : Available when the status is "Disconnected"
                 and contains the last error associated with
                 connecting or disconnecting.
 
        ConnectTime    : the time when the connection was
                 established.
 
    Modem : ConnectSpeed   : the speed of the modem connection
                 in bits/second.
 
    IPSec : Status         : the IPSec-specific status of type
                 SCNetworkConnectionIPSecStatus
 
        ConnectTime    : the time when the connection was
                 established.

```

Other dictionaries could be present for PPPoE, PPTP, and L2TP.

The status dictionary may be extended in the future to contain additional information.

Parameter connection: The SCNetworkConnection to obtain status from.

Returns: Returns the status dictionary. If NULL is returned, the error can be retrieved using the SCError function.

Source

pub fn statistics(&self) -> Option<CFRetained<CFDictionary>>

Returns the statistics of the SCNetworkConnection. A statistic dictionary contains specific dictionaries with statistics for each subcomponent of the service.

For example, a statistics dictionary will contain the following sub-dictionaries, keys, and values:


```text
 
    PPP : BytesIn    :
    PPP : BytesOut   : Contains the number of bytes going up into
               (or coming out of) the network stack for
               any networking protocol without the PPP
               headers and trailers.
 
    PPP : PacketsIn  :
    PPP : PacketsOut : Contains the number of packets going up into
               (or coming out of) the network stack for
               any networking protocol without the PPP
               headers and trailers.
 
    PPP : ErrorsIn   :
    PPP : ErrorsOut  : Contains the number of errors going up into
               (or coming out of) the network stack for
               any networking protocol without the PPP
               headers and trailers.
```

The statistics dictionary may be extended in the future to contain additional information.

Parameter connection: The SCNetworkConnection to obtained statistics from.

Returns: Returns the statistics dictionary. If NULL is returned, the error can be retrieved using the SCError function.

Source

pub unsafe fn start( &self, user_options: Option<&CFDictionary>, linger: bool, ) -> bool

Starts the connection for the SCNetworkConnection. The connection process is asynchronous and the function will return immediately. The connection status can be obtained by polling or by callback. The connection is made with the default settings from the administrator. Some of the settings can be overridden for the duration of the connection. These are specified in an options dictionary. The options dictionary uses the same format as a network service defined in the system configuration preferences schema.

Note: Starting and stopping of connections is implicitly arbitrated. Calling SCNetworkConnectionStart on a connection already started will indicate that the application has interest in the connection and it shouldn’t be stopped by anyone else.

Parameter connection: The SCNetworkConnection to start.

Parameter userOptions: The options dictionary to start the connection with. If userOptions is NULL, the default settings will be used. If userOptions are specified, they must be in the same format as network services stored in the system configuration preferences schema. The options will override the default settings defined for the service.

For security reasons, not all options can be overridden; the appropriate merging of all settings will be done before the connection is established, and inappropriate options will be ignored.

Parameter linger: This parameter indicates whether or not the connection can stay around when the application no longer has interest in it. A typical application should pass FALSE, and the connection will be automatically stopped when the reference is released or if the application quits. If the application passes TRUE, the application can release the reference or exit and the connection will be maintained until a timeout event, until a specific stop request occurs, or until an error is encountered.

Returns: Returns TRUE if the connection was correctly started (the actual connection is not established yet, and the connection status needs to be periodically checked); FALSE if the connection request was not started. The error must be retrieved from the SCError function.

§Safety

user_options generics must be of the correct type.

Source

pub fn stop(&self, force_disconnect: bool) -> bool

Stops the connection for the SCNetworkConnection. The disconnection process is asynchronous and the function will return immediately. The connection status can be obtained by polling or by callback. This function performs an arbitrated stop of the connection. If several applications have marked their interest in the connection, by calling SCNetworkConnectionStart, the call will succeed but the actual connection will be maintained until the last interested application calls SCNetworkConnectionStop.

In certain cases, you might want to stop the connection anyway. In these cases, you set the forceDisconnect argument to TRUE.

Parameter connection: The SCNetworkConnection to stop.

Returns: Returns TRUE if the disconnection request succeeded; FALSE if the disconnection request failed. The error must be retrieved from the SCError function.

Source

pub fn user_options(&self) -> Option<CFRetained<CFDictionary>>

Copies the user options used to start the connection. This is a mechanism a client can use to retrieve the user options previously passed to the SCNetworkConnectionStart function.

Parameter connection: The SCNetworkConnection to obtain options from.

Returns: Returns the service dictionary containing the connection options. The dictionary can be empty if no user options were used. If NULL is returned, the error can be retrieved using the SCError function.

Source

pub fn schedule_with_run_loop( &self, run_loop: &CFRunLoop, run_loop_mode: &CFString, ) -> bool

Schedules a connection with the run loop.

Parameter connection: The SCNetworkConnection to schedule.

Parameter runLoop: The run loop to schedule with.

Parameter runLoopMode: The run loop mode.

Returns: Returns TRUE if the connection is scheduled successfully; FALSE if the scheduling failed. The error can be retrieved using the SCError function.

Source

pub fn unschedule_from_run_loop( &self, run_loop: &CFRunLoop, run_loop_mode: &CFString, ) -> bool

Unschedules a connection from the run loop.

Parameter connection: The SCNetworkConnection to unschedule.

Parameter runLoop: The run loop to unschedule from.

Parameter runLoopMode: The run loop mode.

Returns: Returns TRUE if the connection is unscheduled successfully; FALSE if the unscheduling failed. The error can be retrieved using the SCError function.

Source

pub unsafe fn set_dispatch_queue(&self, queue: Option<&DispatchQueue>) -> bool

Available on crate feature dispatch2 only.

Caller provides a dispatch queue on which the callback contained in connection will run.

Parameter connection: The SCNetworkConnection to notify.

Parameter queue: The libdispatch queue to run the callback on. Pass NULL to disable notifications, and release queue.

Returns: Returns TRUE if the notifications have been enabled/disabled as desired; FALSE if not. The error can be retrieved using the SCError function.

§Safety

queue possibly has additional threading requirements.

Methods from Deref<Target = CFType>§

Source

pub fn downcast_ref<T>(&self) -> Option<&T>
where T: ConcreteType,

Attempt to downcast the type to that of type T.

This is the reference-variant. Use CFRetained::downcast if you want to convert a retained type. See also ConcreteType for more details on which types support being converted to.

Source

pub fn retain_count(&self) -> usize

Get the reference count of the object.

This function may be useful for debugging. You normally do not use this function otherwise.

Beware that some things (like CFNumbers, small CFStrings etc.) may not have a normal retain count for optimization purposes, and can return usize::MAX in that case.