Struct ctru::services::uds::Uds

pub struct Uds { /* private fields */ }

Handle to the UDS service.

Implementations

impl Uds

pub fn service_status(&self) -> ServiceStatus

Retrieve the current status of the service.

pub fn new(username: Option<&str>) -> Result<Self, Error>

Initialise a new service handle. No new_with_buffer_size function is provided, as there isn’t really a reason to use any size other than the default.

The username parameter should be a max 10-byte (not 10 code point!) UTF-8 string, converted to UTF-16 internally. Pass None to use the 3DS’s configured username.

Errors

This function will return an error if the Uds service is already being used, or if the provided username is invalid (longer than 10 bytes or contains a NULL byte).

Example

use ctru::services::uds::Uds;

let uds = Uds::new(None)?;

pub fn scan( &mut self, comm_id: &[u8; 4], additional_id: Option<u8>, whitelist_macaddr: Option<MacAddr6> ) -> Result<Vec<NetworkScanInfo>>

Scan the UDS service for all available beacons broadcasting with the given IDs.

This function must be called to obtain network objects that can later be connected to.

Example

use ctru::services::uds::Uds;
let mut uds = Uds::new(None)?;

let networks = uds.scan(b"HBW\x10", None, None)?;

pub fn network_appdata( &self, network: &NetworkScanInfo, max_size: Option<usize> ) -> Result<Vec<u8>>

Retrieve app data for a network which the service is not connected to.

Example

use ctru::services::uds::Uds;
let mut uds = Uds::new(None)?;

let networks = uds.scan(b"HBW\x10", None, None)?;
let appdata = uds.network_appdata(&networks[0], None)?;

pub fn appdata(&self, max_size: Option<usize>) -> Result<Vec<u8>, Error>

Retrieve app data for the currently connected network.

Errors

This function will return an error if the service is not connected to a network. See Uds::connect_network() to connect to a network.

Example

use ctru::services::uds::{ConnectionType, Uds};
let mut uds = Uds::new(None)?;

let networks = uds.scan(b"HBW\x10", None, None)?;
uds.connect_network(&networks[0], b"udsdemo passphrase c186093cd2652741\0", ConnectionType::Client, 1)?;
let appdata = uds.appdata(None)?;

pub fn connect_network( &mut self, network: &NetworkScanInfo, passphrase: &[u8], connection_type: ConnectionType, channel: u8 ) -> Result<()>

Connect to a network.

Example

use ctru::services::uds::{ConnectionType, Uds};
let mut uds = Uds::new(None)?;

let networks = uds.scan(b"HBW\x10", None, None)?;
uds.connect_network(&networks[0], b"udsdemo passphrase c186093cd2652741\0", ConnectionType::Client, 1)?;

pub fn disconnect_network(&mut self) -> Result<(), Error>

Disconnect from a network.

Errors

This function will return an error if the service is not connected to a network. See Uds::connect_network() to connect to a network.

Example

use ctru::services::uds::{ConnectionType, Uds};
let mut uds = Uds::new(None)?;

let networks = uds.scan(b"HBW\x10", None, None)?;
uds.connect_network(&networks[0], b"udsdemo passphrase c186093cd2652741\0", ConnectionType::Client, 1)?;
uds.disconnect_network()?;

pub fn unbind_context(&mut self) -> Result<(), Error>

Unbind the connection context.

Normally, there’s no reason to call this function, since Uds::disconnect_network() and Uds::destroy_network() both automatically unbind their contexts.

Errors

This function will return an error if no context is currently bound (i.e. the service is neither connected to nor hosting a network). See Uds::connect_network() to connect to a network or Uds::create_network() to create one.

Example

use ctru::services::uds::{ConnectionType, Uds};
let mut uds = Uds::new(None)?;

let networks = uds.scan(b"HBW\x10", None, None)?;
uds.connect_network(&networks[0], b"udsdemo passphrase c186093cd2652741\0", ConnectionType::Client, 1)?;
uds.unbind_context()?;

pub fn channel(&self) -> Result<u8, Error>

Returns the Wi-Fi channel currently in use.

Errors

This function will return an error if the service is currently neither connected to nor hosting a network. See Uds::connect_network() to connect to a network or Uds::create_network() to create one.

Example

use ctru::services::uds::{ConnectionType, Uds};
let mut uds = Uds::new(None)?;

let networks = uds.scan(b"HBW\x10", None, None)?;
uds.connect_network(&networks[0], b"udsdemo passphrase c186093cd2652741\0", ConnectionType::Client, 1)?;
let channel = uds.channel()?;

pub fn wait_status_event(&self, next: bool, wait: bool) -> Result<bool, Error>

Wait for a ConnectionStatus event to occur.

If next is true, discard the current event (if any) and wait for the next one.

If wait is true, block until an event is signalled, else return false if no event.

Always returns true, unless wait is false and no event has been signalled.

Errors

This function will return an error if the service is currently neither connected to nor hosting a network. See Uds::connect_network() to connect to a network or Uds::create_network() to create one.

Example

use ctru::services::uds::{ConnectionType, Uds};
let mut uds = Uds::new(None)?;

let networks = uds.scan(b"HBW\x10", None, None)?;
uds.connect_network(&networks[0], b"udsdemo passphrase c186093cd2652741\0", ConnectionType::Client, 1)?;
if uds.wait_status_event(false, false)? {
    println!("Event signalled");
}

pub fn connection_status(&self) -> Result<ConnectionStatus>

Returns the current ConnectionStatus struct.

Example

use ctru::services::uds::{ConnectionType, Uds};
let mut uds = Uds::new(None)?;

let networks = uds.scan(b"HBW\x10", None, None)?;
uds.connect_network(&networks[0], b"udsdemo passphrase c186093cd2652741\0", ConnectionType::Client, 1)?;
if uds.wait_status_event(false, false)? {
    println!("Connection status event signalled");
    let status = uds.connection_status()?;
    println!("Status: {status:#X?}");
}

pub fn send_packet( &self, packet: &[u8], address: NodeID, channel: u8, flags: SendFlags ) -> Result<(), Error>

Send a packet to the network.

TODO: max size?

Errors

This function will return an error if the service is currently neither connected to nor hosting a network. See Uds::connect_network() to connect to a network or Uds::create_network() to create one. It will also return an error if the service is currently connected to a network as a spectator, as spectators cannot send data, only receive it.

Example

use ctru::services::uds::{ConnectionType, NodeID, SendFlags, Uds};
let mut uds = Uds::new(None)?;

let networks = uds.scan(b"HBW\x10", None, None)?;
uds.connect_network(&networks[0], b"udsdemo passphrase c186093cd2652741\0", ConnectionType::Client, 1)?;
uds.send_packet(b"Hello, World!", NodeID::Broadcast, 1, SendFlags::Default)?;

pub fn pull_packet(&self) -> Result<Option<(Vec<u8>, NodeID)>, Error>

Pull a packet from the network.

Errors

This function will return an error if the service is currently neither connected to nor hosting a network. See Uds::connect_network() to connect to a network or Uds::create_network() to create one.

Example

use ctru::services::uds::{ConnectionType, Uds};
let mut uds = Uds::new(None)?;

let networks = uds.scan(b"HBW\x10", None, None)?;
uds.connect_network(&networks[0], b"udsdemo passphrase c186093cd2652741\0", ConnectionType::Client, 1)?;
let packet = uds.pull_packet()?;

pub fn create_network( &mut self, comm_id: &[u8; 4], additional_id: Option<u8>, max_nodes: Option<u8>, passphrase: &[u8], channel: u8 ) -> Result<()>

Create a new network.

Errors

This function will return an error if the Uds service is already being used.

Example

use ctru::services::uds::Uds;
let mut uds = Uds::new(None)?;

uds.create_network(b"HBW\x10", None, None, b"udsdemo passphrase c186093cd2652741\0", 1)?;

pub fn destroy_network(&mut self) -> Result<(), Error>

Destroy the current network.

Errors

This function will return an error if no network has been created. See Uds::create_network() to create a network.

Example

use ctru::services::uds::Uds;
let mut uds = Uds::new(None)?;

uds.create_network(b"HBW\x10", None, None, b"udsdemo passphrase c186093cd2652741\0", 1)?;
uds.destroy_network()?;

pub fn set_appdata(&self, data: &[u8]) -> Result<(), Error>

Set the app data for the currently hosted network.

Errors

This function will return an error if no network has been created. See Uds::create_network() to create a network. This function will also return an error if the provided buffer is too large (see Uds::MAX_APPDATA_SIZE).

Example

use ctru::services::uds::Uds;
let mut uds = Uds::new(None)?;

uds.create_network(b"HBW\x10", None, None, b"udsdemo passphrase c186093cd2652741\0", 1)?;
uds.set_appdata(b"Test appdata.\0")?;

pub fn wait_data_available(&self, next: bool, wait: bool) -> Result<bool, Error>

Wait for a bind event to occur.

If next is true, discard the current event (if any) and wait for the next one.

If wait is true, block until an event is signalled, else return false if no event.

Always returns true, unless wait is false and no event has been signalled.

Errors

This function will return an error if the service is currently neither connected to nor hosting a network. See Uds::connect_network() to connect to a network or Uds::create_network() to create one.

Example

use ctru::services::uds::{ConnectionType, Uds};
let mut uds = Uds::new(None)?;

let networks = uds.scan(b"HBW\x10", None, None)?;
uds.connect_network(&networks[0], b"udsdemo passphrase c186093cd2652741\0", ConnectionType::Client, 1)?;
if uds.wait_data_available(false, false)? {
    println!("Data available");
}

pub fn eject_client(&self, address: NodeID) -> Result<(), Error>

Eject a client from the network.

Errors

This function will return an error if no network has been created. See Uds::create_network() to create a network.

Example

use ctru::services::uds::{NodeID, Uds};
let mut uds = Uds::new(None)?;

uds.create_network(b"HBW\x10", None, None, b"udsdemo passphrase c186093cd2652741\0", 1)?;
uds.eject_client(NodeID::Node(2))?;

pub fn allow_spectators(&mut self, allow: bool) -> Result<(), Error>

Allow or disallow spectators on the network.

Disallowing spectators will disconnect all spectators currently observing the network.

Errors

This function will return an error if no network has been created. See Uds::create_network() to create a network.

Example

use ctru::services::uds::Uds;
let mut uds = Uds::new(None)?;

uds.create_network(b"HBW\x10", None, None, b"udsdemo passphrase c186093cd2652741\0", 1)?;
uds.allow_spectators(false)?;

pub fn allow_new_clients(&mut self, allow: bool) -> Result<(), Error>

Allow or disallow new clients on the network.

Disallowing new clients will not disconnect any currently connected clients.

Errors

This function will return an error if no network has been created. See Uds::create_network() to create a network.

Example

use ctru::services::uds::Uds;
let mut uds = Uds::new(None)?;

uds.create_network(b"HBW\x10", None, None, b"udsdemo passphrase c186093cd2652741\0", 1)?;
uds.allow_new_clients(false)?;

pub fn node_info(&self, address: NodeID) -> Result<NodeInfo, Error>

Returns the NodeInfo struct for the specified network node.

Errors

This function will return an error if NodeID::None or NodeID::Broadcast is passed.

Example

use ctru::services::uds::{NodeID, Uds};
let mut uds = Uds::new(None)?;

uds.create_network(b"HBW\x10", None, None, b"udsdemo passphrase c186093cd2652741\0", 1)?;
let node_info = uds.node_info(NodeID::Node(2))?;

Trait Implementations

impl Drop for Uds

fn drop(&mut self)

Executes the destructor for this type.