1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<META http-equiv="Content-Style-Type" content="text/css"> 6<TITLE>NWC24 API Introduction</TITLE> 7<LINK rel="stylesheet" type="text/css" href="../CSS/revolution.css"> 8</HEAD> 9<BODY> 10<H1>NWC24 API</H1> 11 12<H2>Introduction</H2> 13<P> 14The NWC24 library makes WiiConnect24 functions, provided by the Wii console, available to applications. 15</P> 16 17<H2>Features</H2> 18<P> 19Functions for performing the following operations are available in the NWC24 library: 20</P> 21<P> 22 <UL> 23<LI>Enabling, disabling, and stopping the automatic send and receive function of WiiConnect24 24<LI>Creating WiiConnect24 messages and saving them to the outbox 25<LI>Getting a list of WiiConnect24 messages in the inbox/outbox 26<LI>Performing a simple search of WiiConnect24 messages in the inbox/outbox 27<LI>Getting the content for a certain WiiConnect24 message from the inbox 28<LI>Deleting WiiConnect24 messages in the inbox/outbox 29<LI>Referencing and searching the console friend roster 30<LI>Registering and deleting entries to and from the console friend roster 31<LI>Registering and deleting to or from the WiiConnect24 download task list 32<LI>Obtaining data that was acquired through download 33<LI>Deleting data that was acquired through download 34 </UL> 35</P> 36 37<H2>Required Libraries and Header Files</H2> 38 39<P> 40When using each feature of the NWC24 library from the application, you should include <code><revolution/nwc24.h></code>, which comes with the RevoEX package. In addition to linking to the various libraries supplied with the Revolution SDK, you must also link to these NWC24 library components: <CODE>nwc24.a</CODE> (debug version: <CODE>nwc24D.a</CODE>), <CODE>ncd.a</CODE> (<CODE>ncdD.a</CODE>), <CODE>net.a</CODE> (<CODE>netD.a</CODE>) and <CODE>vf.a</CODE> (<CODE>vfD.a</CODE>). These components are included in the RevoEX package. 41</P> 42 43<P> 44The NWC24 library uses parts of the <A HREF="../vf/intro.html">VF library</A> for internal file management. For this reason, it is necessary to call <code><a href="../vf/VFInit.html">VFInit(Ex)</a></code> to initialize the VF library in advance before using the NWC24 library. There is only one drive of the VF library that is used internally by the NWC library, and this drive is specially named so that there is little chance of it being overlapped during normal use. 45</P> 46 47<H2>Process Flow</H2> 48<P> 49WiiConnect24 provides round-the-clock transparent service to Wii consoles with enabled network connections. Automatic processes are launched at set intervals in the background, when an application is running or the console is in standby mode, sending and receiving messages and performing downloads. (Automatic processing will not occur in applications that are not linked to the NWC24 library.) 50</P> 51<P> 52The NWC24 functions are used to access the contents obtained within the WiiConnect24 framework and to configure processes. 53</P> 54<P> 55To use the NWC24 functions to access data, the library must first be opened. Use <A href="Misc/NWC24OpenLib.html"><CODE>NWC24OpenLib</CODE></A> to open the library. 56</P> 57<P> 58Because the library internally requires a work area in memory, be sure to pass a pointer to that memory region as an argument. Although the size of this region may change in the future, the capacity required under this version has been set, using the <CODE>NWC24_WORK_MEM_SIZE</CODE> macro. In addition, this memory pointer must be aligned on a 32-byte address boundary. 59</P> 60<P> 61For more about accessing WiiConnect24 content, see descriptions of the following functions: 62</P> 63<UL> 64<LI>Messages: <A href="Message/intro.html">Message API</A>, <A href="Search/intro.html">Message Search Function</A> 65 </LI> 66<LI>Console Friend List: <A href="FriendList/intro.html">Friend List API</A> 67 </LI> 68<LI>Downloads: <A href="Download/intro.html">Download API</A> 69 </LI> 70<LI>Registering message on the "Wii Message Board": <A href="./MsgBoard/intro.html">The Relationship Between the NWC24 APIs and the Wii Message Board</A>, <A href="./Letterform/Letterform.html">Letterform Template</A> 71 </LI> 72</UL> 73<P> 74Most of these functions will result in an error if an attempt is made to use them while the library is not properly opened. 75</P> 76<P> 77Once the necessary processes are complete, use <A href="Misc/NWC24CloseLib.html"><CODE>NWC24CloseLib</CODE></A> to close the library. After closing, the allocated work buffer can be deallocated. 78</P> 79<P> 80Also, automated functionality is halted temporarily while the library is open in order to maintain integrity. Care must be taken because data will not be sent or received, nor will downloads occur, if the library is left open. In addition, functions are available to pause and resume automatic functionality separately from the opening and closing of the library. For more information, see the <A href="Scheduler/intro.html">Scheduler Operation Functions</A>. 81</P> 82<P> 83Apart from programming issues, the NWC24 API sometimes returns errors due to various factors, such as the operating environment. See <A href="./ErrorHandling/intro.html">Error Handling Sequence</A> for more on the proper handling methods. 84</P> 85 86<H2>NWC24 API Limitations</H2> 87<P> 88Internally, the NWC24 API calls synchronous functions, such as NAND; as a result, it may block for a long period of time. In addition, with the exception of some functions, it is not thread-safe.<BR>Consequently, we recommend using the NWC24 API by preparing a thread exclusively for calling its functions. If exclusive control is done by an application, the use of multiple threads will not pose a problem. 89</P> 90 91<H2>NWC24 API Samples</H2> 92<P> 93Simple demos that perform actual message operations using the procedures described above are provided in the directory <CODE>/build/demos/nwc24demo</CODE>. For more information, see the <A href="sampledemos/demos.html">NWC24 Samples</A> 94</P> 95 96 97<H2>See Also</H2> 98<P> 99<A href="./Message/intro.html">Message Function Description</A><br> <A href="./FriendList/intro.html">Friend Roster Function Description</A><br> <A href="./Search/intro.html">Message Search Function Description</A><br><A href="./Scheduler/intro.html">Scheduler Operation Function Description</A><br><A href="./Download/intro.html">Download Function Description</A><br><A href="./MsgBoard/intro.html">The relationship between <CODE>NWC24API</CODE> and Wii Message Board</A><br> <A href="./Letterform/Letterform.html">Letterform Templates</A><br> <A href="./ErrorHandling/intro.html">Error Handling Sequence</A> 100</P> 101 102<H2>Revision History</H2> 103<P> 1042007/10/03 Added mention that application must be linked to NWC24 library for automatic processing to take place.<BR>2007/08/23 Added Error Handling Sequence to the "See Also" section.<BR>2007/07/05 Revised text about Wii Message Board and added link to Letterform Templates.<BR>2007/04/12 Revised portions of the section, Required Libraries and Header Files.<BR>2007/03/07 Added the section, Required Libraries and Header Files.<BR>2007/02/16 Added to "See Also" section. <BR>2006/12/08 Separated the section explaining Message functions and made thorough revisions.<BR>2006/09/29 Matched details to the current specification.<BR>2006/09/10 Changed the reference target to <CODE>NWC24OpenLib/NWC24CloseLib</CODE>.<BR>2006/09/01 Added functions. Matched changes in the reference file placement.<BR>2006/08/01 Initial version. 105</P> 106 107<hr><p>CONFIDENTIAL</p></body> 108</HTML>