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.
-
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. 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 throughezNetCtlGetStatus()
is sufficient. - state
-
Indicates connection state returned from
sceEENetCtlGetState()
orsceInetCtlGetState()
. 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
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 theezNetCnfCombination_t.status
field. For example, AOL dialup configurations will be tagged withsceNETCNF_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:
- Reading the file from the CD/DVD interferes with other asynchronous disc read operations, which can result in potential crashes due to bad data.
- 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. SeeezNetCnfGetProperties()
.
- 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.