libctru  v1.6.0
Data Structures | Macros | Enumerations | Functions
uds.h File Reference

UDS(NWMUDS) local-WLAN service. More...

Go to the source code of this file.

Data Structures

struct  udsNodeInfo
 Node info struct. More...
 
struct  udsConnectionStatus
 Connection status struct. More...
 
struct  udsNetworkStruct
 Network struct stored as big-endian. More...
 
struct  udsBindContext
 
struct  nwmScanInputStruct
 General NWM input structure used for AP scanning. More...
 
struct  nwmBeaconDataReplyHeader
 General NWM output structure from AP scanning. More...
 
struct  nwmBeaconDataReplyEntry
 General NWM output structure from AP scanning, for each entry. More...
 
struct  udsNetworkScanInfo
 Output structure generated from host scanning output. More...
 

Macros

#define UDS_MAXNODES   16
 Maximum number of nodes(devices) that can be connected to the network.
 
#define UDS_BROADCAST_NETWORKNODEID   0xFFFF
 Broadcast value for NetworkNodeID / alias for all NetworkNodeIDs.
 
#define UDS_HOST_NETWORKNODEID   0x1
 NetworkNodeID for the host(the first node).
 
#define UDS_DEFAULT_RECVBUFSIZE   0x2E30
 Default recv_buffer_size that can be used for udsBind() input / code which uses udsBind() internally.
 
#define UDS_DATAFRAME_MAXSIZE   0x5C6
 Max size of user data-frames.
 
#define UDS_CHECK_SENDTO_FATALERROR(x)   (R_FAILED(x) && x!=0xC86113F0)
 Check whether a fatal udsSendTo error occured(some error(s) from udsSendTo() can be ignored, but the frame won't be sent when that happens).
 

Enumerations

enum  {
  UDSNETATTR_DisableConnectSpectators = BIT(0),
  UDSNETATTR_DisableConnectClients = BIT(1),
  UDSNETATTR_x4 = BIT(2),
  UDSNETATTR_Default = BIT(15)
}
 
enum  {
  UDS_SENDFLAG_Default = BIT(0),
  UDS_SENDFLAG_Broadcast = BIT(1)
}
 
enum  udsConnectionType {
  UDSCONTYPE_Client = 0x1,
  UDSCONTYPE_Spectator = 0x2
}
 

Functions

Result udsInit (size_t sharedmem_size, const char *username)
 Initializes UDS. More...
 
void udsExit (void)
 Exits UDS.
 
Result udsGenerateNodeInfo (udsNodeInfo *nodeinfo, const char *username)
 Generates a NodeInfo struct with data loaded from system-config. More...
 
Result udsGetNodeInfoUsername (const udsNodeInfo *nodeinfo, char *username)
 Loads the UTF-16 username stored in the input NodeInfo struct, converted to UTF-8. More...
 
bool udsCheckNodeInfoInitialized (const udsNodeInfo *nodeinfo)
 Checks whether a NodeInfo struct was initialized by NWM-module(not any output from udsGenerateNodeInfo()). More...
 
void udsGenerateDefaultNetworkStruct (udsNetworkStruct *network, u32 wlancommID, u8 id8, u8 max_nodes)
 Generates a default NetworkStruct for creating networks. More...
 
Result udsScanBeacons (void *outbuf, size_t maxsize, udsNetworkScanInfo **networks, size_t *total_networks, u32 wlancommID, u8 id8, const u8 *host_macaddress, bool connected)
 Scans for networks via beacon-scanning. More...
 
Result udsSetApplicationData (const void *buf, size_t size)
 This can be used by the host to set the appdata contained in the broadcasted beacons. More...
 
Result udsGetApplicationData (void *buf, size_t size, size_t *actual_size)
 This can be used while on a network(host/client) to get the appdata from the current beacon. More...
 
Result udsGetNetworkStructApplicationData (const udsNetworkStruct *network, void *buf, size_t size, size_t *actual_size)
 This can be used with a NetworkStruct, from udsScanBeacons() mainly, for getting the appdata. More...
 
Result udsBind (udsBindContext *bindcontext, u16 NetworkNodeID, bool spectator, u8 data_channel, u32 recv_buffer_size)
 Create a bind. More...
 
Result udsUnbind (udsBindContext *bindcontext)
 Remove a bind. More...
 
bool udsWaitDataAvailable (const udsBindContext *bindcontext, bool nextEvent, bool wait)
 Waits for the bind event to occur, or checks if the event was signaled. More...
 
Result udsPullPacket (const udsBindContext *bindcontext, void *buf, size_t size, size_t *actual_size, u16 *src_NetworkNodeID)
 Receives data over the network. More...
 
Result udsSendTo (u16 dst_NetworkNodeID, u8 data_channel, u8 flags, const void *buf, size_t size)
 Sends data over the network. More...
 
Result udsGetChannel (u8 *channel)
 Gets the wifi channel currently being used. More...
 
Result udsCreateNetwork (const udsNetworkStruct *network, const void *passphrase, size_t passphrase_size, udsBindContext *context, u8 data_channel, u32 recv_buffer_size)
 Starts hosting a new network. More...
 
Result udsConnectNetwork (const udsNetworkStruct *network, const void *passphrase, size_t passphrase_size, udsBindContext *context, u16 recv_NetworkNodeID, udsConnectionType connection_type, u8 data_channel, u32 recv_buffer_size)
 Connect to a network. More...
 
Result udsDestroyNetwork (void)
 Stop hosting the network.
 
Result udsDisconnectNetwork (void)
 Disconnect this client device from the network.
 
Result udsEjectClient (u16 NetworkNodeID)
 This can be used by the host to force-disconnect client(s). More...
 
Result udsEjectSpectator (void)
 This can be used by the host to force-disconnect the spectators. More...
 
Result udsUpdateNetworkAttribute (u16 bitmask, bool flag)
 This can be used by the host to update the network attributes. More...
 
Result udsSetNewConnectionsBlocked (bool block, bool clients, bool flag)
 This uses udsUpdateNetworkAttribute() for (un)blocking new connections to this host. More...
 
Result udsAllowSpectators (void)
 This uses udsUpdateNetworkAttribute() for unblocking new spectator connections to this host. More...
 
Result udsGetConnectionStatus (udsConnectionStatus *output)
 This loads the current ConnectionStatus struct. More...
 
bool udsWaitConnectionStatusEvent (bool nextEvent, bool wait)
 Waits for the ConnectionStatus event to occur, or checks if the event was signaled. More...
 
Result udsGetNodeInformation (u16 NetworkNodeID, udsNodeInfo *output)
 This loads a NodeInfo struct for the specified NetworkNodeID. More...
 

Detailed Description

UDS(NWMUDS) local-WLAN service.

https://3dbrew.org/wiki/NWM_Services

Function Documentation

◆ udsAllowSpectators()

Result udsAllowSpectators ( void  )

This uses udsUpdateNetworkAttribute() for unblocking new spectator connections to this host.

See udsEjectSpectator() for blocking new spectators.

Examples
network/uds/source/uds.c.

◆ udsBind()

Result udsBind ( udsBindContext bindcontext,
u16  NetworkNodeID,
bool  spectator,
u8  data_channel,
u32  recv_buffer_size 
)

Create a bind.

Parameters
bindcontextThe output bind context.
NetworkNodeIDThis is the NetworkNodeID which this bind can receive data from.
spectatorFalse for a regular bind, true for a spectator.
data_channelThis is an arbitrary value to use for data-frame filtering. This bind will only receive data frames which contain a matching data_channel value, which was specified by udsSendTo(). The data_channel must be non-zero.
recv_buffer_sizeSize of the buffer under sharedmem used for temporarily storing received data-frames which are then loaded by udsPullPacket(). The system requires this to be >=0x5F4. UDS_DEFAULT_RECVBUFSIZE can be used for this.

◆ udsCheckNodeInfoInitialized()

bool udsCheckNodeInfoInitialized ( const udsNodeInfo nodeinfo)

Checks whether a NodeInfo struct was initialized by NWM-module(not any output from udsGenerateNodeInfo()).

Parameters
nodeinfoInput NodeInfo struct.
Examples
network/uds/source/uds.c.

◆ udsConnectNetwork()

Result udsConnectNetwork ( const udsNetworkStruct network,
const void *  passphrase,
size_t  passphrase_size,
udsBindContext context,
u16  recv_NetworkNodeID,
udsConnectionType  connection_type,
u8  data_channel,
u32  recv_buffer_size 
)

Connect to a network.

Parameters
networkThe NetworkStruct, you can use udsScanBeacons() for this.
passphraseRaw input passphrase buffer.
passphrase_sizeSize of the passphrase buffer.
contextOptional output bind context which will be created for this host.
recv_NetworkNodeIDThis is the NetworkNodeID passed to udsBind() internally.
connection_typeType of connection, see the udsConnectionType enum values.
data_channelThis is the data_channel value which will be passed to udsBind() internally.
recv_buffer_sizeThis is the recv_buffer_size value which will be passed to udsBind() internally.
Examples
network/uds/source/uds.c.

◆ udsCreateNetwork()

Result udsCreateNetwork ( const udsNetworkStruct network,
const void *  passphrase,
size_t  passphrase_size,
udsBindContext context,
u8  data_channel,
u32  recv_buffer_size 
)

Starts hosting a new network.

Parameters
networkThe NetworkStruct, you can use udsGenerateDefaultNetworkStruct() for generating this.
passphraseRaw input passphrase buffer.
passphrase_sizeSize of the passphrase buffer.
contextOptional output bind context which will be created for this host, with NetworkNodeID=UDS_BROADCAST_NETWORKNODEID.
data_channelThis is the data_channel value which will be passed to udsBind() internally.
recv_buffer_sizeThis is the recv_buffer_size value which will be passed to udsBind() internally.
Examples
network/uds/source/uds.c.

◆ udsEjectClient()

Result udsEjectClient ( u16  NetworkNodeID)

This can be used by the host to force-disconnect client(s).

Parameters
NetworkNodeIDTarget NetworkNodeID. UDS_BROADCAST_NETWORKNODEID can be used to disconnect all clients.

◆ udsEjectSpectator()

Result udsEjectSpectator ( void  )

This can be used by the host to force-disconnect the spectators.

Afterwards new spectators will not be allowed to connect until udsAllowSpectators() is used.

Examples
network/uds/source/uds.c.

◆ udsGenerateDefaultNetworkStruct()

void udsGenerateDefaultNetworkStruct ( udsNetworkStruct network,
u32  wlancommID,
u8  id8,
u8  max_nodes 
)

Generates a default NetworkStruct for creating networks.

Parameters
networkThe output struct.
wlancommIDUnique local-WLAN communications ID for each application.
id8Additional ID that can be used by the application for different types of networks.
max_nodesMaximum number of nodes(devices) that can be connected to the network, including the host.
Examples
network/uds/source/uds.c.

◆ udsGenerateNodeInfo()

Result udsGenerateNodeInfo ( udsNodeInfo nodeinfo,
const char *  username 
)

Generates a NodeInfo struct with data loaded from system-config.

Parameters
nodeinfoOutput NodeInfo struct.
usernameIf set, this is the UTF-8 string to convert for use in the struct. Max len is 10 characters without NUL-terminator.

◆ udsGetApplicationData()

Result udsGetApplicationData ( void *  buf,
size_t  size,
size_t *  actual_size 
)

This can be used while on a network(host/client) to get the appdata from the current beacon.

Parameters
bufAppdata buffer.
sizeMax size of the output buffer.
actual_sizeIf set, the actual size of the appdata written into the buffer is stored here.
Examples
network/uds/source/uds.c.

◆ udsGetChannel()

Result udsGetChannel ( u8 channel)

Gets the wifi channel currently being used.

Parameters
channelOutput channel.
Examples
network/uds/source/uds.c.

◆ udsGetConnectionStatus()

Result udsGetConnectionStatus ( udsConnectionStatus output)

This loads the current ConnectionStatus struct.

Parameters
outputOutput ConnectionStatus struct.
Examples
network/uds/source/uds.c.

◆ udsGetNetworkStructApplicationData()

Result udsGetNetworkStructApplicationData ( const udsNetworkStruct network,
void *  buf,
size_t  size,
size_t *  actual_size 
)

This can be used with a NetworkStruct, from udsScanBeacons() mainly, for getting the appdata.

Parameters
bufAppdata buffer.
sizeMax size of the output buffer.
actual_sizeIf set, the actual size of the appdata written into the buffer is stored here.
Examples
network/uds/source/uds.c.

◆ udsGetNodeInformation()

Result udsGetNodeInformation ( u16  NetworkNodeID,
udsNodeInfo output 
)

This loads a NodeInfo struct for the specified NetworkNodeID.

The broadcast alias can't be used with this.

Parameters
NetworkNodeIDTarget NetworkNodeID.
outputOutput NodeInfo struct.
Examples
network/uds/source/uds.c.

◆ udsGetNodeInfoUsername()

Result udsGetNodeInfoUsername ( const udsNodeInfo nodeinfo,
char *  username 
)

Loads the UTF-16 username stored in the input NodeInfo struct, converted to UTF-8.

Parameters
nodeinfoInput NodeInfo struct.
usernameThis is the output UTF-8 string. Max len is 10 characters without NUL-terminator.
Examples
network/uds/source/uds.c.

◆ udsInit()

Result udsInit ( size_t  sharedmem_size,
const char *  username 
)

Initializes UDS.

Parameters
sharedmem_sizeThis must be 0x1000-byte aligned.
usernameOptional custom UTF-8 username(converted to UTF-16 internally) that other nodes on the UDS network can use. If not set the username from system-config is used. Max len is 10 characters without NUL-terminator.
Examples
network/uds/source/uds.c.

◆ udsPullPacket()

Result udsPullPacket ( const udsBindContext bindcontext,
void *  buf,
size_t  size,
size_t *  actual_size,
u16 src_NetworkNodeID 
)

Receives data over the network.

This data is loaded from the recv_buffer setup by udsBind(). When a node disconnects, this will still return data from that node until there's no more frames from that node in the recv_buffer.

Parameters
bindcontextBind context.
bufOutput receive buffer.
sizeSize of the buffer.
actual_sizeIf set, the actual size written into the output buffer is stored here. This is zero when no data was received.
src_NetworkNodeIDIf set, the source NetworkNodeID is written here. This is zero when no data was received.
Examples
network/uds/source/uds.c.

◆ udsScanBeacons()

Result udsScanBeacons ( void *  outbuf,
size_t  maxsize,
udsNetworkScanInfo **  networks,
size_t *  total_networks,
u32  wlancommID,
u8  id8,
const u8 host_macaddress,
bool  connected 
)

Scans for networks via beacon-scanning.

Parameters
outbufBuffer which will be used by the beacon-scanning command and for the data parsing afterwards. Normally there's no need to use the contents of this buffer once this function returns.
maxsizeMax size of the buffer. @Param networks Ptr where the allocated udsNetworkScanInfo array buffer is written. The allocsize is sizeof(udsNetworkScanInfo)*total_networks. @Param total_networks Total number of networks stored under the networks buffer.
wlancommIDUnique local-WLAN communications ID for each application.
id8Additional ID that can be used by the application for different types of networks.
host_macaddressWhen set, this code will only return network info from the specified host MAC address. @connected When not connected to a network this must be false. When connected to a network this must be true.
Examples
network/uds/source/uds.c.

◆ udsSendTo()

Result udsSendTo ( u16  dst_NetworkNodeID,
u8  data_channel,
u8  flags,
const void *  buf,
size_t  size 
)

Sends data over the network.

Parameters
dst_NetworkNodeIDDestination NetworkNodeID.
data_channelSee udsBind().
flagsSend flags, see the UDS_SENDFLAG enum values.
bufInput send buffer.
sizeSize of the buffer.
Examples
network/uds/source/uds.c.

◆ udsSetApplicationData()

Result udsSetApplicationData ( const void *  buf,
size_t  size 
)

This can be used by the host to set the appdata contained in the broadcasted beacons.

Parameters
bufAppdata buffer.
sizeSize of the input appdata.
Examples
network/uds/source/uds.c.

◆ udsSetNewConnectionsBlocked()

Result udsSetNewConnectionsBlocked ( bool  block,
bool  clients,
bool  flag 
)

This uses udsUpdateNetworkAttribute() for (un)blocking new connections to this host.

Parameters
blockWhen true, block the specified connection types(bitmask set). Otherwise allow them(bitmask clear).
clientsWhen true, (un)block regular clients.
flagWhen true, update UDSNETATTR_x4. Normally this should be false.
Examples
network/uds/source/uds.c.

◆ udsUnbind()

Result udsUnbind ( udsBindContext bindcontext)

Remove a bind.

Parameters
bindcontextThe bind context.
Examples
network/uds/source/uds.c.

◆ udsUpdateNetworkAttribute()

Result udsUpdateNetworkAttribute ( u16  bitmask,
bool  flag 
)

This can be used by the host to update the network attributes.

If bitmask 0x4 is clear in the input bitmask, this clears that bit in the value before actually writing the value into state. Normally you should use the below wrapper functions.

Parameters
bitmaskBitmask to clear/set in the attributes. See the UDSNETATTR enum values.
flagWhen false, bit-clear, otherwise bit-set.

◆ udsWaitConnectionStatusEvent()

bool udsWaitConnectionStatusEvent ( bool  nextEvent,
bool  wait 
)

Waits for the ConnectionStatus event to occur, or checks if the event was signaled.

This event is signaled when the data from udsGetConnectionStatus() was updated internally.

Returns
Always true. However if wait=false, this will return false if the event wasn't signaled.
Parameters
nextEventWhether to discard the current event and wait for the next event.
waitWhen true this will not return until the event is signaled. When false this checks if the event was signaled without waiting for it.
Examples
network/uds/source/uds.c.

◆ udsWaitDataAvailable()

bool udsWaitDataAvailable ( const udsBindContext bindcontext,
bool  nextEvent,
bool  wait 
)

Waits for the bind event to occur, or checks if the event was signaled.

This event is signaled every time new data is available via udsPullPacket().

Returns
Always true. However if wait=false, this will return false if the event wasn't signaled.
Parameters
bindcontextThe bind context.
nextEventWhether to discard the current event and wait for the next event.
waitWhen true this will not return until the event is signaled. When false this checks if the event was signaled without waiting for it.