nn::uds::CTR::CreateNetwork Function

Syntax

nn::Result CreateNetwork(
     u8 subId,
     u8 maxEntry,
     bit32 localId,
     const char passphrase[],
     size_t passphraseLength,
     const void * pData,
     size_t dataSize
);

Arguments

Name Description
in subId Communication mode ID. Set this to a value between 0x00 and 0xFE.
in maxEntry Maximum number of nodes that can connect to the network. This value can be up to NODE_MAX, including the local device.
in localId The local communication ID. Specify the value generated by CreateLocalCommunicationId.
in passphrase[] String holding the seed of the passphrase to use for wireless layer encryption. With UDS, communication can only be established if uniqueId and passphrase match.
in passphraseLength Passphrase length. Specify a value between UDS_PASSPHRASE_LENGTH_MIN and UDS_PASSPHRASE_LENGTH_MAX, inclusive.
in pData Pointer to the optional data you want to set for the beacon.
in dataSize Size of the optional data you want to set for the beacon. Specify a number equal to or less than NET_DESC_APPDATA_SIZE_MAX.

Return Values

Returns the function's execution result. Returns one of the Result values listed below.
Value Description
Result::IsSuccess Successfully established local communication and began operating as a master.
ResultNotInitialized The library is not initialized. Execute the Initialize function.
ResultInvalidState Not in an executable state. Returned when executed in a state other than STATE_DISCONNECTED.
ResultOutOfRange The specified argument value was not in the valid range for the argument. Try again, specifying a valid value for the argument.
ResultWirelessOff Entered wireless-disabled mode. Re-initialization is required.
ResultTooLarge The dataSize exceeds NET_DESC_APPDATA_SIZE_MAX.
ResultInvalidPointer pData is NULL. NULL is allowed when dataSize is 0.
A value other than the above Failed for reasons other than those given above.

Description

Sets optional data for the beacon and builds a new network.

Approximately 800 ms is needed to complete this because auto-selection of channels and other operations must be performed.

Using this API function allows you to set optional data for the beacon, when building the network. To update the optional data for the beacon after the network has been constructed, use the SetApplicationDataToBeacon function. The maximum size of this optional data is NET_DESC_APPDATA_SIZE_MAX bytes. Since it is not encrypted, note that it can be collected by any general device, such as a computer. Other devices can obtain this data by calling Scan, while they are connected as clients or spectators. This function is thread-safe.

Revision History

2011/09/07
Standardized notation for wireless-disabled mode.
2011/02/21
Added a timing guideline to the Description. Indicated that the maximum value for maxEntry is NODE_MAX.
2011/01/25
Changed size of passphrase used from "fewer than 255 (provisional)" to "at least 8 and no more than 255," and confirmed.
Changed to automatically set the channel to use, with the old function to specify the channel now limited to debugging purposes.
2010/10/15
Expanded the information on the return values.
2010/06/14
Initial version.

CONFIDENTIAL