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 throughezNetCtlGetStatus()
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
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 thestatus
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:
- 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()
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, versussceEENETCTL_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. SeeezNetCnfGetProperties()
.
- 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, versussceEENETCTL_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.