ezNetCnf - Library Reference

[SCE CONFIDENTIAL DOCUMENT]
Copyright ® 2002-4 Sony Computer Entertainment America. All Rights Reserved

## Overview

The ezNetCnf library provides read-only access to network settings stored in Your Network Configuration (YNC) files. Use ezNetCnfGetCombinationList() to enumerate a list of available Combinations, which are pairs of ISP and hardware device settings. Use the returned display data to generate a YNC listing for the user to select. When the user makes a selection, use ezNetCnfGetProperties() to load in the complete settings.

The ezNetCtl library controls the bringing up of the Network Interface (I/F). Use ezNetCtlSetProperties() to apply previously loaded setting data to an I/F. Use ezNetCtlUpInterface() to start the link negotiation process undertaken by the network stack. Finally use ezNetCtlGetStatus() to poll and report details on the link negotiation process.

### Architecture

Each ezNet library consist of an EE RPC client talking to an IOP RPC server, which require certain base SCE libraries and modules in turn. The ezNet functions are provided on top of NetCnf and {EENet,Inet}Ctl primitives, internalizing many TRC-related complexities so you can avoid common pitfalls and mistakes, and ultimately save time.

    EE      eznetcnf.a          eznetctl_inet.a        eznetctl_eenet.a
                 ::                  ::                eenetctl.a
                 ::                  ::                libeenet.a
                 ::                  ::                     ::
    ------------ :: ---------------- :: ------------------- :: --------------
                 ::                  ::                     ::
    IOP     eznetcnf.irx        eznetctl.irx           ezentctl.irx
              netcnf.irx         inetctl.irx           eenetctl.irx
                                    inet.irx           ent_devm.irx
                                  netcnf.irx             netcnf.irx

The ezNetCnf library can be used with any network stack, including SN's NDK. While ezNetCtl is highly stack-dependent, the APIs are identical between the two implementations provided for Inet and libeenet. The included sample code targets both Inet and libeenet, only requiring conditional compilation for stack initialization and stack details output.

### SIF RPC Reentry

ezNetCnf and ezNetCtl use separate and independent SIF RPC servers. You can safely call an ezNetCnf routine while an ezNetCtl routine is outstanding. However, as with all SIF RPC implementations, reentry is forbidden within the same server. You cannot make overlapping calls within ezNetCnf, or ezNetCtl.

When using netcnfif callbacks to support netcnf.irx with Memory Card library 2, take extra care to prevent ezNetCnf routines from causing libmc2 RPC reentry. A conflict occurs if one the following functions tries to read from the memory card, while an asynchronous libmc2 RPC is already pending.

- `ezNetCnfGetCount()`
- `ezNetCnfGetCombinationList()`
- `ezNetCnfGetProperties()`
- `ezNetCtlSetCombination()`

For single-threaded applications, use `sceMc2Sync()` to block for the pending libmc2 operation to complete. Multi-threaded implementations require creating your own libmc2 access mutex. The original Memory Card library (libmc) is immune to this conflict, because netcnf.irx can directly access the files via IOP stdio.

    // unsafe
    sceMc2GetInfoAsync(socket, NULL);
    num = ezNetCnfGetCount("mc0:");

    // safe
    sceMc2GetInfoAsync(socket, NULL);
    sceMc2Sync(NULL, NULL);
    num = ezNetCnfGetCount("mc0:");

    // safe (original MC library)
    sceMcGetInfo(port, 0, NULL, NULL, NULL);
    num = ezNetCnfGetCount("mc0:");

### SIF DMA Data Alignment

The following functions use SIF DMA to fill their respective destination data structures, which require strict 64-byte data alignment. Using incorrectly aligned arguments now returns `-SCE_EINVAL` along with a TTY warning.

- `ezNetCnfGetCombinationList(..., ezNetCnfCombinationList_t *)`
- `ezNetCnfGetProperties(..., sceNetcnfifData_t *)`
- `ezNetCtlSetProperties(sceNetcnfifData_t *)`

In eznetcnf.h and netcnfif.h, the relevant typedefs already include the alignment attribute. Static variables will be automatically aligned. Use `memalign()` if you prefer to use dynamic allocation. You must not declare these as automatic variables on a function stack, since alignment cannot be guaranteed.

## Data Structures

### ezNetCnfCombination_t

This structure contains the various display names of a network configuration, necessary for enumeration and display to the end-user. Note this does not contain the actual configuration settings, which are available from a separate `sceNetcnfifData_t` structure defined in netcnfif.h.

    typedef struct ezNetCnfCombination {
        int status;
        int iftype;
        char combinationName[kStrDisplaySize];
        char ifcName[kStrDisplaySize];
        char devName[kStrDisplaySize];
    } ezNetCnfCombination_t;

status
  (status >= 0) indicates a usable configuration, (status < 0) indicates an abnormal condition or invalid configuration. Do not allow the user to select or activate an invalid configuration.
iftype
  Indicates the link encapulation type used by this network configuration. Useful to determine which modules and drivers need to be loaded.
  - `eIftypeUnknown` (not valid for ezNetCnf)
  - `eIftypeLoop` (not valid for ezNetCnf)
  - `eIftypeEther`
  - `eIftypePPP`
  - `eIftypePPPoE`
combinationName[]
  Contains the display name of the combination setting file, "Combination#". This parameter is used for `ezNetCnfGetProperties()`, `ezNetCtlSetCombination()`. This name should not be directly displayed.
ifcName[]
  Contains the display name of the Internet service provider setting file, encoded as UTF-8. The saved setting name may have up to 256 bytes, but ifcName is truncated after 64 bytes (and null-terminated). Supported hiragana and katakana can require 3 bytes per character. Titles must be able to display at least 20 such characters of the ISP setting name.
devName[]
  Contains the display name of the hardware setting file, in the format "Vendor/Product" and encoded as plain ASCII. Similar to ifcName, devName is also truncated after 64 bytes (and null-terminated). Titles must be able to display at least 20 characters of the hardware setting name.

### ezNetCnfCombinationList_t

This structure captures a complete list of `ezNetCnfCombinationList_t` elements from a single netdb management file. See additional YNC Display Examples document for implementation requirements and recommendations.

    typedef struct ezNetCnfCombinationList {
        int listLength;
        unsigned int defaultNumber;
        unsigned int netdbOrder[kMaxCombinations];
        ezNetCnfCombination_t list[kMaxCombinations];
    } ezNetCnfCombinationList_t;

listLength
  Indicates the maximum number of configurations for this list. This value will be 6 for a list stored on a memory card, and 10 (`kMaxCombinations`) everywhere else.
defaultNumber
  Indicates which combination should be considered as the user default. Valid values will be in the range 1 to listLength, inclusive.
netdbOrder[]
  This array stores the most recently added order of combination settings, identical to the configuration list order of the ntgui2 utility. Your title may enumerate the configuration list using this order or ordinal succession.
list[]
  This array contains all configurations that were found. You should use `ezNetCnfGetCombination()` to iterate over this list.

### ezNetCtlStatus_t

Throughout a network connection process, use this structure to receive status updates to the active network I/F.

    typedef struct ezNetCtlStatus {
        int ifid;
        int ifid2;
        char ifname[kIfnameSize];
        char ifname2[kIfnameSize];
        int iftype;
        int error;
        int state;
        int link;
    } ezNetCtlStatus_t;

ifid
  Inet: Id of active physical I/F. For non-PPPoE connections, call `sceInetInterfaceControl(ifid...)` to get properties such as the IP address.
ifid2
  Inet: Id of active virtual I/F, if applicable. For PPPoE connections, call `sceInetInterfaceControl(ifid2...)` to get properties such as the IP address.
ifname
  libeenet: Name of active physical I/F. For non-PPPoE connections, call `sceEENetGetIfinfo(ifname...)` to get properties such as the IP address.
ifname2
  libeenet: Name of active virtual I/F, if applicable. For PPPoE connections, call `sceEENetGetIfinfo(ifname2...)` to get properties such as the IP address.
iftype
  Indicates the link encapsulation type of the active I/F.
  - `eIftypeUnknown`
  - `eIftypeLoop`
  - `eIftypeEther`
  - `eIftypePPP`
  - `eIftypePPPoE`
error
  For stateful DHCP, PPP, and PPPoE connections, indicates error returned from `sceEENetCtlGetErrorCode()`. ezNetCtl recreates compatible codes for Inet. See sce/include/ee/libeenet/eenetctlerrno.h. As these error codes may easily be mis-interpreted as DNAS error codes, do not display this field to the end user. The localized error messages available through `ezNetCtlGetStatus()` is sufficient.
state
  Indicates connection state of the active I/F.
  - `sce{EE,I}NETCTL_S_DETACHED`: terminal state
  - `sce{EE,I}NETCTL_S_STARTING`: transient state
  - `sce{EE,I}NETCTL_S_RETRYING`: transient state (for PPP connections only)
  - `sce{EE,I}NETCTL_S_STARTED`: terminal state
  - `sce{EE,I}NETCTL_S_STOPPING`: transient state
  - `sce{EE,I}NETCTL_S_STOPPED`: terminal state
  - `sceEENETCTL_S_DETACHING`: transient state
link
  Indicates the Ethernet cable link status.
  - -1: link status not available
  - 0: link down
  - 1: link up
  This field is updated at most once per second, and its value is only valid for Ethernet and PPPoE connections. See the Network Link Status Precautions technote if you intend to use this field.

## ezNetCnf Functions

### ezNetCnfInit()

Initialize library and bind to eznetcnf.irx RPC services.

    int ezNetCnfInit(void);

Return value:
  0 for initialization success.
  < 0 if eznetcnf.irx module is not resident.

### ezNetCnfExit()

Unbind RPC and unload eznetcnf.irx.

    int ezNetCnfExit(void);

Return value:
  0 after unload succeeds.
  < 0 if module cannot be stopped or unloaded.

### ezNetCnfGetCount()

Count the number of network configurations at the specified location.

    int ezNetCnfGetCount(
    	const char *netdb);

netdb
  Path to netdb management file. Specify a full path for a host-based netdb; "mc0:" or "mc1:" is sufficient for the netdb on a memory card.

Return value:
  > 0 when at least 1 configuration is found.
  0 when no configurations are found.

### ezNetCnfGetCombinationList()

Retrieve a list of network configurations, necessary for further enumeration and display to the end-user.

    int ezNetCnfGetCombinationList(
    	const char *netdb,
    	int flags,
    	ezNetCnfCombinationList_t *addr);

netdb
  Path to netdb management file. Specify a full path for a host-based netdb; "mc0:" or "mc1:" is sufficient for the netdb on a memory card.
flags
  Specify filter options to identify network configurations based on certain characteristics. Configurations that match a filter will be tagged with a specific `ezNetCnfCombination_t.status` value. By checking the `status` field, the title program can pre-emptively reject invalid or inappropriate configurations.
  `ezNetCnfRejectAOLDialup`
    Tag AOL Dialup configurations with `sceNETCNF_AOL_CONFIGURATION`
  `ezNetCnfRejectModem`
    Tag modem-based configurations with `sceNETCNF_INVALID_TYPE`
  `ezNetCnfRejectUSB`
    Tag USB hardware-based configurations with `sceNETCNF_INVALID_TYPE`
  `ezNetCnfLimitLAN`
    To support Ethernet/LAN game modes, tag PPP and PPPoE configurations with `sceNETCNF_INVALID_TYPE`
addr
  Destination address of `ezNetCnfCombinationList_t` result.

Return value:
  > 0 when there is at least one valid configuration.
  0 when there are no valid configurations.
  < 0 when errors result from netcnf.irx, including `sceNETCNFIF_MAGIC_ERROR`.

### ezNetCnfGetCombination()

`ezNetCnfCombinationList_t` accessor that returns a specified network configuration.

    ezNetCnfCombination_t *ezNetCnfGetCombination(
    	ezNetCnfCombinationList_t *pList,
    	int number);

pList
  Previously retrieved network configuration list.
number
  The requested network configuration number, starting from 1.

Return value:
  !NULL for success.
  NULL for failure (due to invalid pList argument).

### ezNetCnfGetDefault()

`ezNetCnfCombinationList_t` accessor that returns the default network configuration.

    ezNetCnfCombination_t *ezNetCnfGetDefault(
    	ezNetCnfCombinationList_t *pList);

pList
  Previously retrieved network configuration list.

Return value:
  !NULL for success.
  NULL for failure (due to invalid pList argument).

### ezNetCnfGetProperties()

Read in network configuration settings into an EE-side `sceNetcnfifData_t` data structure. Using this and `ezNetCtlSetProperties()` allows you to unload memory card modules before loading the complete network stack.

    int ezNetCnfGetProperties(
    	const char *netdb,
    	const char *combinationName,
    	sceNetcnfifData_t *addr);

netdb
  Path to netdb management file. Specify a full path for a host-based netdb; "mc0:" or "mc1:" is sufficient for the netdb on a memory card.
combinationName
  Do not use ifcName here.
addr
  Destination address of `sceNetcnfifData_t` result.

Return value:
  0 for success.
  < 0 for error.

## ezNetCtl Functions

### ezNetCtlInit()

Initialize library and bind to eznetctl.irx RPC services.

    int ezNetCtlInit(void);

Return value:
  0 for initialization success.
  < 0 if eznetctl.irx module is not resident.

### ezNetCtlExit()

Unbind RPC and unload eznetctl.irx.

    int ezNetCtlExit(
    	int flags);

flags
  By default (flags=0), this routine shuts down the ezNetCtl library, unbinds RPC and unloads the IOP module. Use the options below to modify the default behavior.
  `ezNetCtlKeepEventHandler`
    libeenet: Preserve the EE-side event handler and leave the following non-RPC functions available for use.
    - `ezNetCtlUpInterface()`
    - `ezNetCtlDownInterface()`
    - `ezNetCtlGetStatus()`
    - `ezNetCtlWaitEventTO()`
  `ezNetCtlKeepModule`
    Keep the IOP module resident, in case a custom IOP module manager is responsible for loading and unloading of eznetctl.irx.

Return value:
  0 for success.
  < 0 if module cannot be stopped or unloaded.

### ezNetCtlPreloadModemCnf()

This function allows you to manually preload the modem dialing configuration file. This configuration file is also a required startup argument to the modem device driver, and otherwise autoloaded when bringing up a PPP I/F. Using this function can address two potential problems caused by autoloading:

1. Reading the file from the CD/DVD interferes with other asynchronous disc read operations, which can result in potential crashes due to bad data.
2. Loading also incurs an IOP memory allocation, which can cause unexpected memory fragmentation.

Using `ezNetCtlPreloadModemCnf()` still incurs the file read and the memory allocation, but gives you precise control of when these operations take place. In general, you should call this function as early-on as possible, while making sure you have exclusive access to the CD/DVD.

    int ezNetCtlPreloadModemCnf(
    	const char *path);

path
  Path of modem configuration file, which must be identical to the path specified to the modem driver.

Return value:
  0 for success.
  < 0 for preload failure.

### ezNetCtlUnloadModemCnf()

This function allows you to un-preload the modem dialing configuration file. This operation also automatically occurs when ezNetCtl exits.

    int ezNetCtlUnloadModemCnf(void);

Return value:
  0 for success.
  < 0 for unload failure.

### ezNetCtlSetCombination()

Load a network configuration and bind it to an available I/F. Internally, this function waits for up to 2 seconds using `ezNetCtlWaitEventTO()` to return the terminal I/F event observed.

    int ezNetCtlSetCombination(
    	const char *netdb,
    	const char *combinationName);

netdb
  Path to netdb management file. Specify a full path for a host-based netdb; "mc0:" or "mc1:" is sufficient for the netdb on a memory card.
combinationName
  Do not use ifcName here.

Return value:
  > 0 after successfully binding the configuration to an I/F, returns the observed I/F event. This will always be `sceEENETCTL_IEV_Attach` with {ee,i}netctl running in no_auto mode, versus `sceEENETCTL_IEV_{Attach,UpCompleted,DownCompleted,DetachCompleted}` when running in auto mode.
  < 0 for load or bind failure.

### ezNetCtlSetProperties()

Bind specified network configuration settings to an available I/F. Internally, this function waits for up to 2 seconds using `ezNetCtlWaitEventTO()` to return the terminal I/F event observed.

    int ezNetCtlSetProperties(
    	sceNetcnfifData_t *data);

data
  Previously retrieved `sceNetcnfifData` settings. See `ezNetCnfGetProperties()`.

Return value:
  > 0 after successfully binding the configuration to an I/F, returns the observed I/F event. This will always be `sceEENETCTL_IEV_Attach` with {ee,i}netctl running in no_auto mode, versus `sceEENETCTL_IEV_{Attach,UpCompleted,DownCompleted,DetachCompleted}` when running in auto mode.
  < 0 for bind failure.

### ezNetCtlUpInterface()

Bring up the active I/F.

    int ezNetCtlUpInterface(void);

Return value:
  0 for success.
  < 0 for `sce{EENet,Inet}UpInterface()` failure.

### ezNetCtlDownInterface()

Shut down the active I/F.

    int ezNetCtlDownInterface(void);

Return value:
  0 for success.
  < 0 for `sce{EENet,Inet}DownInterface()` failure.

### ezNetCtlGetStatus()

Poll the active I/F for its connection status. After the connection starts, this function should be called much less frequently, if at all.

    int ezNetCtlGetStatus(
    	ezNetCtlStatus_t *status,
    	char *msgBuf,
    	unsigned int msgBufSize);

status
  Destination of `ezNetCtlStatus_t` result.
msgBuf
  Destination of status message buffer. Specify NULL to skip message localization.
msgBufSize
  Size of status message buffer.

Return value:
  0 for success.
  < 0 for `sce{EENet,Inet}CtlGetState()` failure.

### ezNetCtlWaitEventTO()

Poll or wait for the active I/F to reach a terminal state and return the corresponding event. In wait mode, the caller blocks for the duration of the specified timeout.

Warning: For Ethernet connections, if there is no Ethernet link or no DHCP/PPPoE server, the network I/F will remain in the `sce{EE,I}NETCTL_S_STARTING` state indefinitely. Under such circumstances, this function will not return if called with no timeout.

    int ezNetCtlWaitEventTO(
    	int ms);

ms
  Timeout in milliseconds. Specify 0 to poll without blocking. Specify -1 for no timeout.

Return value:
  `sceEENETCTL_IEV_Attach` when I/F binds to the network configuration.
  `sceEENETCTL_IEV_UpCompleted` when I/F succeeds in establishing a connection.
  `sceEENETCTL_IEV_DownCompleted` when I/F fails to connect or is shut down.
  `sceEENETCTL_IEV_DetachCompleted` when I/F is detached from the stack.
  -1 if timeout expired.

### ezNetCtlSwapMessageTables()

Swap out the localization message tables. See eznetcnf/lib-src/i18n.c for detailed message table format and usage.

    void ezNetCtlSwapMessageTables(
    	ezMsgEntry_t *errorMsgs,
    	ezMsgEntry_t *phaseMsgs,
    	ezMsgEntry_t *stateMsgs);

errorMsgs
  Replacement error messages table. Specify NULL to revert to default English table.
phaseMsgs
  Replacement phase messages table. Specify NULL to revert to default English table.
stateMsgs
  Replacement state messages table. Specify NULL to revert to default English table.

Overview

Data Structures
  ezNetCnfCombination_t
  ezNetCnfCombinationList_t
  ezNetCtlStatus_t

ezNetCnf Functions
  ezNetCnfInit
  ezNetCnfExit
  ezNetCnfGetCount
  ezNetCnfGetCombinationList
  ezNetCnfGetCombination
  ezNetCnfGetDefault
  ezNetCnfGetProperties

ezNetCtl Functions
  ezNetCtlInit
  ezNetCtlExit
  ezNetCtlPreloadModemCnf
  ezNetCtlUnloadModemCnf
  ezNetCtlSetCombination
  ezNetCtlSetProperties
  ezNetCtlUpInterface
  ezNetCtlDownInterface
  ezNetCtlGetStatus
  ezNetCtlWaitEventTO
  ezNetCtlSwapMessageTables

YNC Display Examples