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

Preface

SIF RPC Re-entrancy

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, re-entrancy is not provided 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 re-entrancy. 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. Possible values:
  • eIftypeUnknown
  • eIftypeLoop
  • 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. See NetCnf Display Examples for serveral recommended display formats.
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.

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 (PS2), and 10 (kMaxCombinations) everywhere else.
defaultNumber
Indicates which combination should be considered as the user default. This value will be in the range 1 to listLength, inclusive.
netdbOrder[]
This array stores the original order of the combination settings in the netdb management file. You should not need to refer to this array.
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 specific: Id of active physical I/F. For non-PPPoE connections, call sceInetInterfaceControl(ifid...) to get properties such as the IP address.
ifid2
Inet specific: Id of active virtual I/F, if applicable. For PPPoE connections, call sceInetInterfaceControl(ifid2...) to get properties such as the IP address.
ifname
Name of active physical I/F. For non-PPPoE connections, call sceEENetGetIfinfo(ifname...) to get properties such as the IP address.
ifname2
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.
  • sceEENET_IFTYPE_UNKNOWN (not valid for ezNetCtl)
  • sceEENET_IFTYPE_LOOP (not valid for ezNetCtl)
  • sceEENET_IFTYPE_ETHER
  • sceEENET_IFTYPE_PPP
  • sceEENET_IFTYPE_PPPOE
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 returned from sceEENetCtlGetState() or sceInetCtlGetState(). Possible values:
  • 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. Possible values:
  • -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
Currently, only the flag ezNetCnfCheckProvider is available. If (flags & ezNetCnfCheckProvider == 1), the library will identify special provider settings by tagging the ezNetCnfCombination_t.status field. For example, AOL dialup configurations will be tagged with sceNETCNF_AOL_CONFIGURATION (-20). Otherwise, all configurations are treated as normal.
In practical terms, if your title supports AOL dialup, call:
ezNetCnfGetCombinationList(netdb, 0, addr);
If your title does not support AOL dilaup, call:
ezNetCnfGetCombinationList(netdb, ezNetCnfCheckProvider, addr);
addr
Destination address of ezNetCnfCombinationList_t result.
Return value:
6 for loading from memory card netdb with at least 1 configuration.
10 for loading from other netdb with at least 1 configuration.
0 when no configurations were found.
< 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.

Inet version: eznetctl.irx will not unload while a network interface is still being brought up, since the configuration environment is still in use and must not be disposed. After this shutdown routine succeeds, all eznetctl_inet functions become unavailable.

libeenet version: ezentctl.irx may be unloaded at any time. However, RPC functions will become unavailable.

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 flag options below to modify the default behavior:
  • libeenet version: Specify ezNetCtlKeepEventHandler to preserve the EE-side event handler, thus leaving the following non-RPC functions available for use.
    • ezNetCtlUpInterface()
    • ezNetCtlDownInterface()
    • ezNetCtlGetStatus()
    • ezNetCtlWaitEventTO()
  • Specify ezNetCtlKeepModule to keep RPC alive and the IOP module resident. Use this option if you stop and unload modules via your own IOP module manager.
Return value:
0 for success.
< 0 if module cannot be stopped or unloaded.

ezNetCtlPreloadModemCnf()

Inet version requires inetctl.irx 2.5.6 or later.
libeenet version requires eenetctl.irx 2.8.0 or later.
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() will still incur 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()

Inet version requires inetctl.irx 2.5.6 or later.
libeenet version requires eenetctl.irx 2.8.0 or later.
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 for a sce{EE,I}NETCTL_IEV_Attach event to confirm configuration success, using ezNetCtlWaitEventTO().

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:
sce{EE,I}NETCTL_IEV_ATTACH for success.
< 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 for a sce{EE,I}NETCTL_IEV_Attach event to confirm configuration success, using ezNetCtlWaitEventTO().

int ezNetCtlSetProperties(
	sceNetcnfifData_t *data);
data
Previously retrieved sceNetcnfifData settings. See ezNetCnfGetProperties().
Return value:
sce{EE,I}NETCTL_IEV_ATTACH for success.
-1 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()

Wait for the active I/F to reach a terminal state and return the corresponding event. The caller blocks for the duration of the specified timeout.

libeenet version: Since the EE kernel does not enforce SemaParam.maxCount, this function has been modified to consume all of the semaphore current count before returning. This prevents the eznetctl semaphore from overflowing, and improves the reliability of the returned I/F event result.

int ezNetCtlWaitEventTO(
	int ms);
ms
Timeout in milliseconds. Specify -1 for no 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.
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 otherwise shuts down.
  • sceEENETCTL_IEV_DetachCompleted when I/F is logically 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.