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

  bindcontext | The output bind context.
  NetworkNodeID | This is the NetworkNodeID which this bind can receive data from.
  spectator | False for a regular bind, true for a spectator.
  data_channel | This 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_size | Size 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

  nodeinfo | Input 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

  network | The NetworkStruct, you can use udsScanBeacons() for this.
  passphrase | Raw input passphrase buffer.
  passphrase_size | Size of the passphrase buffer.
  context | Optional output bind context which will be created for this host.
  recv_NetworkNodeID | This is the NetworkNodeID passed to udsBind() internally.
  connection_type | Type of connection, see the udsConnectionType enum values.
  data_channel | This is the data_channel value which will be passed to udsBind() internally.
  recv_buffer_size | This 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

  network | The NetworkStruct, you can use udsGenerateDefaultNetworkStruct() for generating this.
  passphrase | Raw input passphrase buffer.
  passphrase_size | Size of the passphrase buffer.
  context | Optional output bind context which will be created for this host, with NetworkNodeID=UDS_BROADCAST_NETWORKNODEID.
  data_channel | This is the data_channel value which will be passed to udsBind() internally.
  recv_buffer_size | This 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

  NetworkNodeID | Target 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

  network | The output struct.
  wlancommID | Unique local-WLAN communications ID for each application.
  id8 | Additional ID that can be used by the application for different types of networks.
  max_nodes | Maximum 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

  nodeinfo | Output NodeInfo struct.
  username | If 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

  buf | Appdata buffer.
  size | Max size of the output buffer.
  actual_size | If 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

  channel | Output channel.

Examples
  network/uds/source/uds.c.

## udsGetConnectionStatus()

Result udsGetConnectionStatus | ( | udsConnectionStatus * | output | ) |

This loads the current ConnectionStatus struct.

Parameters

  output | Output 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

  buf | Appdata buffer.
  size | Max size of the output buffer.
  actual_size | If 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

  NetworkNodeID | Target NetworkNodeID.
  output | Output 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

  nodeinfo | Input NodeInfo struct.
  username | This 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_size | This must be 0x1000-byte aligned.
  username | Optional 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

  bindcontext | Bind context.
  buf | Output receive buffer.
  size | Size of the buffer.
  actual_size | If set, the actual size written into the output buffer is stored here. This is zero when no data was received.
  src_NetworkNodeID | If 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

  outbuf | Buffer 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.
  maxsize | Max 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.
  wlancommID | Unique local-WLAN communications ID for each application.
  id8 | Additional ID that can be used by the application for different types of networks.
  host_macaddress | When 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_NetworkNodeID | Destination NetworkNodeID.
  data_channel | See udsBind().
  flags | Send flags, see the UDS_SENDFLAG enum values.
  buf | Input send buffer.
  size | Size 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

  buf | Appdata buffer.
  size | Size 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

  block | When true, block the specified connection types(bitmask set). Otherwise allow them(bitmask clear).
  clients | When true, (un)block regular clients.
  flag | When true, update UDSNETATTR_x4. Normally this should be false.

Examples
  network/uds/source/uds.c.

## udsUnbind()

Result udsUnbind | ( | udsBindContext * | bindcontext | ) |

Remove a bind.

Parameters

  bindcontext | The 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

  bitmask | Bitmask to clear/set in the attributes. See the UDSNETATTR enum values.
  flag | When 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

  nextEvent | Whether to discard the current event and wait for the next event.
  wait | When 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

  bindcontext | The bind context.
  nextEvent | Whether to discard the current event and wait for the next event.
  wait | When true this will not return until the event is signaled. When false this checks if the event was signaled without waiting for it.