NintendoSDK-NEX for NX 4.0.0 RC

# 1. Introduction

The Cafe NEX package is the expanded communication library for the NX version of the NintendoSDK. It includes features for matchmaking, ranking, and data stores. (NEX is an abbreviation for network extensions.) We use NX-NEX to refer to the NintendoSDK-NEX for NX below. NX-NEX includes both 32-bit and 64-bit binaries for each of the Windows, NX on Windows, and NX versions. To view the revision history for the library, see Documents/manual/history4.html.

The current version is under development. In the future, the Windows and NX on Windows versions will only be available for development. Users will log into the game server using predefined user names and passwords for the time being because there is no account system at present.

This library uses encryption technology.

# 2. System Requirements

Visual Studio 2013 Update 5 and Visual Studio 2015 Update 3 must be installed to build NX-NEX. The NintendoSDK itself and NintendoSDK VSI for NX are required to build the Windows version. The NintendoSDK NX Add-on is required to build the NX on Windows version. The NintendoSDK NX Add-on and NintendkSDK Clang for NX are required to build the NX version. The NintendoSDK-NEX for NX OpenSSL Package is required to build the Windows version and NX on Windows version.

# 3. Installation

Expand this package in a directory whose name includes neither spaces nor Japanese characters.
For the remainder of this document, this directory is referred to as NINTENDO_SDK_NEX_ROOT.

# 4. How to Use

Set this directory path as the NINTENDO_SDK_NEX_ROOT environment variable and include nex.h.
You do not need to set this environment variable if NINTENDO_SDK_ROOT has been set as an environment variable in NintendoSDK, and the NintendoSDK and NintendoSDK-NEX directories have been configured in parallel as follows.

• C:\Users\<User name>\Documents\NDIEnv\<Environment name>\NintendoSDK
• C:\Users\<User name>\Documents\NDIEnv\<Environment name>\NintendoSDK-NEX

If you plan to manually specify the include path and the libraries path, use the following paths. Use the Develop version library for the NX version Debug build.

• $(NINTENDO_SDK_NEX_ROOT)\Include •$(NINTENDO_SDK_NEX_ROOT)\Libraries

# 5. File List

• Include
• Contains the headers that you can include in applications.

• Libraries
• Contains the libraries that you can link to from applications.

• Tools
• Contains the tools needed for building.

• Samples
• Contains the samples.

• Documents
• Contains the API Reference and other documentation.

# 6. Samples

Open the solution files under $(NINTENDO_SDK_NEX_ROOT)\Samples\Applications\NEX with Visual Studio, and then build. Solution files with Generic included in the file names are the Windows version, and those with NX included in the file names are the NX on Windows and NX versions. This documentation refers to items that run in a Windows environment (including the NX on Windows version) as Windows versions. ## Running Sample Demos When specifying a user name and password for logging into a predefined game server, specify the game server URI, access key, login user name, and password in the runtime arguments -uri, -key, -user, and -pass. • NX Version Startup Example • %NINTENDO_SDK_ROOT%\Tools\CommandLineTools\RunOnTarget.exe RendezVous_CallContext.nca -- -uri "https://g27851c00-dd1.s.n.srv.nintendo.net/" -key 12345678 -user testuser_0 -pass "my password" • Windows Version Startup Example • RendezVous_CallContext.exe -uri "https://g27851c00-dd1.s.n.srv.nintendo.net/" -key 12345678 -user testuser_0 -pass "my password" When specifying a game server ID and access key for logging in (login for network service account using account library), after commenting out the NEX_FORCE_USE_DEBUG_LOGIN_DIRECT macro in $(NINTENDO_SDK_NEX_ROOT)\Samples\Applications\NEX\common\NexUtilDefs.h, and setting the Application.aarch64.lp64.meta or Application.arm.ilp32.meta ApplicationId item in %NINTENDO_SDK_ROOT%\Resources\SpecFiles to the 0x0100289000012000 ApplicationId for samples, build in the NSP format with the AuthoringTool included in Visual Studio or the SDK, and then launch it. Building and running NSPD files is different from building and running NSP files. No control data, defined within the META file, is included within the built executable file. You need to configure the following types of settings separately. Begin by preparing a META file with an appropriate ApplicationId specified. This is the same as when building an NSP file. Use the createnspmeta command within AuthoringTool to create an NCD for control data. Next, place the generated control0.ncd and meta0.ncd files under the executable NSPD file's directory. At that point, the directory has the following configuration.

XXXX.nspd/
┣ program0.ncd
┣ control0.ncd
┗ meta0.ncd

You can include control data when debugging NSPD applications in Visual Studio, or when running RunOnTarget for those applications in Visual Studio, when you use the settings indicated above. In the future, the above settings will occur automatically when building NSPD files in Visual Studio. (The Windows version is not supported in this version.)
• Launching the NX (NSPD) Version
• %NINTENDO_SDK_ROOT%\Tools\CommandLineTools\AuthoringTool\AuthoringTool.exe createnspmeta -o D:\path\to\RendezVous_CallContext.nspd --meta %NINTENDO_SDK_ROOT%\Resources\SpecFiles\Application.aarch64.lp64.meta --type Application
cp -r D:\path\to\RendezVous_CallContext.nspd\output.nspd\control0.ncd D:\path\to\RendezVous_CallContext.nspd\output.nspd\meta0.ncd D:\path\to\RendezVous_CallContext.nspd
%NINTENDO_SDK_ROOT%\Tools\CommandLineTools\RunOnTarget.exe D:\path\to\RendezVous_CallContext.nspd
• Launching the NX (NSP) Version
• %NINTENDO_SDK_ROOT%\Tools\CommandLineTools\ControlTarget.exe install-application D:\path\to\RendezVous_CallContext.nsp
%NINTENDO_SDK_ROOT%\Tools\CommandLineTools\ControlTarget.exe launch-application 0x0100289000012000

In the Windows version, the environment variable can be used instead of the parameter. Run after setting the game server URI, access key, login user name, and password to environment variables RV_TEST_URI, RV_TEST_KEY, RV_TEST_USER, and RV_TEST_PASS.

The default is identical to when specifying environment variables, as follows. There may be cases where identical user names are chosen because user names are randomly selected, and it is possible that users logged into the game server with the same user names will be disconnected. Use the specified user name and password except for when running samples.

set RV_TEST_URI=https://g27851c00-dd1.s.n.srv.nintendo.net/
set RV_TEST_KEY=12345678
set RV_TEST_USER=testuser_ + "random number between 0 and 9999"

$(NINTENDO_SDK_NEX_ROOT)\Samples\Applications\NEX\common\NexUtil.h and NEXDEMO_ACCESS_KEY are ignored. For more information, see $(NINTENDO_SDK_NEX_ROOT)\Samples\Applications\NEX\common\SigloNexUtil.cpp.

HTTP proxy settings are required, depending on the environment, for connecting with the game server. Set the environment variables as follows when setting HTTP proxies for the Windows version.

Example:
set https_proxy=http://example.com:8080

Refer to the Nintendo SDK manual when setting HTTP proxies for the NX version.

## String Notation in Samples

Strings are enclosed in NEX_T() in the sample program code to switch to wide characters based on the environment. (Example: NEX_T("ABC")) In NintendoSDK-NEX, NEX_T("ABC") becomes "ABC"regardless of the character encoding set in Visual Studio, like Unicode or MBCS.

# 7. Notes

• Initialization and Finalization
• You must initialize the library before using any of the library's features, and you must finalize the library when you are done.

1. Initialization Process
2. If you are using an application-specific allocator, first set the allocator by using the MemoryManager:SetBasicMemoryFunctions() function.
The memory-allocation function that you specify must return a valid pointer.
Applications should handle the process as follows.
• Shut down the library if you are going to allocate more memory than was prepared.
• In advance, allocate an amount of memory close to the amount that was used when the library was executing before shutdown — typically between several kilobytes to several dozen kilobytes. If memory allocation fails during the initialization process, this previously allocated memory is released.
(Because memory is freed, the memory-allocation process can now succeed.) Then shut down the library.

Next, call the GlobalVariables::AcquireInstance() function to create the global variables used by the library.

3. Finalization Process
4. Call the GlobalVariables::ReleaseInstance() function to free the global variables used by this library.

• Build Types and Link Libraries
• When linking NEX libraries, link the NEX library with the same build type as the build type of the application that uses NEX. Applications may not run normally if the same build type is not used.

• libcurl-related Libraries (Windows version)
• The Windows version of NEX does not use the version of libcurl that comes packaged with NintendoSDK. As a result, the libnn_nex_openssl.lib and libnn_nex_libcurl.lib files in the NEX package must be linked explicitly. When you are using NexProjectSettings.props in VisualStudio, these libraries are included in the \$(NexBasicLibraries) definition and do not need to be added again.
libnn_nex_openssl.lib is included in the separately available NEX OpenSSL package.
Do not call any NintendoSDK nn::ssl API when using libcurl after linking to libnn_nex_openssl.lib and libnn_nex_libcurl.lib.

• libcurl-related Libraries (NX version)
• In the NX version, the libcurl.a file in NintendoSDK must be linked explictly.

• The Character Encoding That Can Be Used With NEX
• NintendoSDK-NEX uses the UTF-8 format internally. Because the String class constructor can take values using the wchar_t type, this can be used to convert Unicode strings defined with wchar_t to UTF-8.

• Updating the Game Server
• The library checks the server version when a user logs in, and if the server version is older than the one required by the library, it is not possible to log in to the game server. Accordingly, if the NEX library used by the application is updated, the game server also must be updated. Make the game server update request from OMAS. (Game servers do not update automatically.)

This library includes software developed by Quazal Technologies Inc.
However, direct all requests for support and queries concerning this library to Nintendo.

The following OSS libraries are included in this library's binaries.

## libCurl

/***************************************************************************
*                                  _   _ ____  _
*  Project                     ___| | | |  _ \| |
*                             / __| | | | |_) | |
*                            | (__| |_| |  _ <| |___
*                             \___|\___/|_| \_\_____|
*
* Copyright (C) 1998 - 2012, Daniel Stenberg, , et al.
*
* This software is licensed as described in the file COPYING, which
* you should have received as part of this distribution. The terms
* are also available at http://curl.haxx.se/docs/copyright.html.
*
* You may opt to use, copy, modify, merge, publish, distribute and/or sell
* copies of the Software, and permit persons to whom the Software is
* furnished to do so, under the terms of the COPYING file.
*
* This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
* KIND, either express or implied.
*
***************************************************************************/



## Wslay

The MIT License

Copyright (c) 2011, 2012, 2015 Tatsuhiro Tsujikawa

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


## OpenSSL

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit.