[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.

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.

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.