functions.html

来自「palm的pocketc」· HTML 代码 · 共 1,088 行 · 第 1/5 页

    (1 tick typically equals 1/100 second) allowed between consecutive bytes.
    Returns 0 for timeout, -1 for line error, 1 for success.</li>
  <li><em>serbuffsize(int size)</em> - allocates a serial buffer of the given size (+32 bytes
    for PalmOS overhead). This function should only be called if you seem to be having serial
    overrun problems. Returns 1 on success, 0 on failure.</li>
  <li><i>sersenda(pointer pData, int size)</i> - send <i>size</i> bytes of data
    from an array. The memory pointed to by <i>pData</i> must be ints or chars,
    and each element my be one byte.</li>
  <li><i>serrecva(pointer pData, int size)</i> - receive <i>size</i> bytes of
    data into an array. The memory pointed to by <i>pData</i> must be ints or
    chars, and each element will be filled with one byte.</li>
  <li><i>unpack(pointer pInts, pointer pSerData, string dataSizes, int count)</i> -
    unpack an array of <i>count</i> bytes into 1- 2- and 4-byte ints. <i>pSerData</i> is a
    memory block/array of bytes (either ints or chars); <i>pInts</i> is a memory
    block/array of ints which will be filled with unpacked ints; <i>dataSizes </i>is a string describing the data. Each number (1,2,4) in
    <i>dataSizes </i>represents an int. If a number is preceeded by '&lt;', then the bytes are
    assumed to be in little-endian order; big-endian is assumed otherwise. The <i>dataSizes</i>
    string is repeatedly processed until <i>count</i> bytes are unpacked.
    Example:
    from <i>serrecva</i><i>()</i>, you get 8 bytes which should be interpreted
    as a big-endian 16-bit it, a little-endian 16-bit int, and a 32-bit big-endian
    int. The code might be:</li>
</ul>

<blockquote>
  <pre>int data[3], sbuff[8];
...
serrecva(sbuff, 8);
unpack(data, sbuff, &quot;2&lt;24&quot;, 8);</pre>
</blockquote>

<h3>System</h3>

<ul>
  <li><i>sleep(int ms)</i> - sleeps for ms milliseconds. </li>
  <li><i>deepsleep(int sec)</i> - turns the device off for <i>sec</i> seconds.
    This is only accurate to within 30 seconds, your mileage may vary. </li>
  <li><i>resetaot()</i> - resets the auto off timer. </li>
  <li><i>getsysval(int index)</i> - gets a system value. Currently supported values: [0]
    Username, [1] OS Version, [2] OS Version string, [3] Serial number, [4]
    ticks per second.</li>
  <li><em>launch(string creatorID)</em> - closes PocketC and launches the application with the
    given creator ID. Returns 0 on failure, does not return on success. Ex:
    launch(&quot;memo&quot;); // Opens memo pad. Ex: launch(&quot;lnch&quot;); // Opens the
    application launcher if running OS 3.0</li>
  <li><em>clipget()</em> - returns the current clipboard contents (if text).</li>
  <li><em>clipset(string text)</em> - sets the text clipboard contents.</li>
  <li><i>exit()</i> - exits immediately. On OS 3.0+, exits to application
    launcher. On OS 2.x, exits to PocketC.</li>
  <li><i>atexit(pointer func)</i> - The function whose address is passed to this
    function is called immediately when the user attempts to switch apps (but
    not when the user presses the Done button or the Applet|Stop menu item).
    Such a function must run very quickly and may not affect the display or use
    the event system (through event(), puts(), alert(), graphics functions,
    etc.). <b>Warning:</b> it is not generally safe to make assumptions about
    where your applet was suspended when <i>func</i> began to execute.</li>
  <li><i>version()</i> - returns the installed PocketC version. For version
    4.0.3, this returns 403.</li>
</ul>

<h3>Memory Management</h3>

<p>A few notes that will help understand the following section: In a normal computer,
memory is divided into bytes and words. PocketC divides its memory into elements called
&quot;values&quot;. Each value stores a basic PocketC type (int, char, float, string,
pointer). Also, each element of memory knows its own type (thus the need for the <em>settype()</em>
function). 

<ul>
  <li><em>malloc(int size)</em> - allocates a block of <em>size</em> values of type <em>int</em>,
    but of undefined value. Returns a pointer to the block or 0 on failure. The types of the
    elements in the returned block can be changed from <em>int</em> to any other type using
    the <em>settype()</em> function. This function is deprecated, <i>malloct()</i>
    should be used instead.</li>
  <li><i>malloct(int nBlocks, string blockTypes)</i> - allocates <i>nBlocks</i>
    blocks of memory whose types are described by <i>blockTypes</i>. <i>blockTypes</i>
    is a string of characters representing data types ( 'i'-int, 'p'-pointer,
    'c'-char, 'f'-float, 's'-string). The memory block is initialized to 0 for
    numeric types and &quot;&quot; for strings. e.g. <i>malloct</i>(3, &quot;piis&quot;)
    will allocate 12 values -- the first will be a pointer, the second/third an
    int, the fourth a string, the fifth another pointer, the sixth/seventh ints...
    A type can be preceded by a count number to repeat the type - 'p2is' is the
    same as 'piis', '8f' is the same as 'ffffffff'.</li>
  <li><em>free(pointer ptr)</em> - releases the memory of the block pointed to by <em>ptr</em>
    which was previously allocated by <em>malloc()</em>. When an applet exits, all blocks that
    are still allocated will automatically be freed to prevent memory leaks.</li>
  <li><em>settype(pointer ptr, int size, char type)</em> - sets the type of the <em>size</em>
    contiguous values starting at <em>ptr</em> to the type specified by <em>type</em> ('i' for
    int or pointer, 'f' for float, 'c' for char, 's' for string). Use this function only on
    memory allocated by <em>malloc()</em>. Returns 0 on error.</li>
  <li><em>typeof(pointer ptr)</em> - returns the type of the value pointed to by <em>ptr</em>,
    ('i' for int or pointer, 'c' for char, 'f' for float, 's' for string, 'o' for other).</li>
  <li><em>memcpy(pointer dest, pointer src, int size)</em> - copies the data from the block of
    size <em>size</em> pointed to by <em>src</em> to the block pointed to by <em>dest</em>.
    The types of the destination values is not preserved. (i.e. if <em>dest</em> points to a
    string, and <em>src</em> points to an int, the memory pointed to by <em>dest</em> will be
    changed to an int)..</li>
</ul>
<h3>Networking</h3>
<p>PocketC's networking support is based on BSD-style sockets. This 
documentation assumes you understand the functionality and is not intended to 
teach you to use BSD-style sockets. Currently only TCP 
sockets are supported. Almost all of the networking functions
returns 0 on success and an error code 
on failure. To interpret the error code, you can call the neterror() function 
provided in neterror.h (in PocketC's UtilCode directory) which will convert the 
error code to a string.</p>
<p>All the functions that take and return addresses use a string representation.
An address string is a dotted IP address with optional port, such as:
<code>&quot;129.22.104.22:80&quot;</code> An empty string is interpreted as the
local address. Thus, when calling sockbind(), only a port needs to be specified:
<code>&quot;:1234&quot;</code>. All socket methods (and the DNS methods) have a
timeout associated with them. This timeout value is globally set using netsettimeout().
</p>
<ul>
  <li><b>General APIs</b><ul>
      <li><i>netopen()</i> - opens the networking stack and connects it to the network according to system settings. 
      This function must be called before any other networking function. Return 0 on success.</li>
      <li><i>netclose()</i> - closes the networking stack.</li>
      <li><i>netlocaladdr()</i> - gets the local address string of the device 
      when connected, otherwise an empty string. This function always returns 
      the empty string when run on the emulator.</li>
      <li><i>nethostbyname(string name, pointer paddr)</i> - Looks up the given
      <i>name</i> using DNS, putting the resulting address in the string pointed 
      to by <i>paddr</i>. Returns 0 on success.</li>
      <li><i>nethostbyaddr(string addr, pointer pname)</i> - Looks up the given
      <i>addr</i> using DNS, putting the resulting name in the string pointed 
      to by <i>pname</i>. Returns 0 on success.</li>
      <li><i>netgettimeout()</i> - gets the maximum wait time for network 
      operations, defined in ticks. -1 implies infinite.</li>
      <li><i>netsettimeout(int timeout)</i> - sets the maximum wait time for 
      network operations, defined in ticks. -1 implies infinite.</li>
    </ul>
  </li>
  <li><b>Sockets</b><ul>
      <li><i>sockopen(pointer pid)</i> - opens a TCP socket, returning the new 
      socket id in the int pointed to by <i>pid</i>. Returns 0 on success.</li>
      <li><i>sockclose(int id)</i> - closes the given socket. You must call this 
      function when you are finished using a socket. Returns 0 on success.</li>
      <li><i>sockaccept(int id, pointer pnewid)</i> - accepts a new socket, and 
      returns the new socket id in the int pointed to by <i>pnewid</i>. Returns 0 
      on success.</li>
      <li><i>sockbind(int id, string localAddr)</i> - binds the given socket to 
      a local address. Generally only a port needs to be specified, such as
      <code>&quot;:1234&quot;</code>. Returns 0 on success.</li>
      <li><i>sockconnect(int id, string addr)</i> - connects a socket to the the 
      remote address <i>addr</i>. Returns 0 on success.</li>
      <li><i>socklisten(int id, int backlog)</i> - starts listening on the given 
      socket, with the specified <i>backlog</i>. Currently the Palm OS only 
      supports 1 for the <i>backlog</i> parameter. Returns 0 on success.</li>
      <li><i>socksend(int id, pointer data, string format, int count)</i> - 
      sends the data pointed to by <i>data</i> and described by <i>format</i> (with 
      the format repeated <i>count</i> times). <i>format</i> is the same as 
      described by dbwritex(). Returns 0 on success.</li>
      <li><i>sockrecv(int id, pointer data, string format, int count)</i> - 
      receives data into the memory pointed to by <i>data</i> and described by <i>format</i> (with 
      the format repeated <i>count</i> times). <i>format</i> is the same as 
      described by dbwritex(). Returns 0 on success.</li>
      <li><i>sockshutdown(int id, int dir)</i> - shuts down the socket for the 
      given direction <i>dir</i>. Available directions are input[0], output[1], 
      and both[2].</li>
      <li><i>socklocaladdr(int id)</i> - returns the local address of a 
      connected socket.</li>
      <li><i>sockremoteaddr(int id)</i> - returns the remote address of a 
      connected socket.</li>
    </ul>
  </li>
</ul>
<h3>VFS</h3>
<p>The Palm OS support for Virtual File Systems (VFS) allows an application to 
read and write files to removable storage, such as a compact flash card or 
memory stick. Almost all of the VFS functions returns 0 on success and an error 
code on failure. To interpret the error code, you can call the vfserror() 
function 
provided in vfserror.h (in PocketC's UtilCode directory) which will convert the 
error code to a string. This file also contains #defines for many useful VFS 
constants. Some methods do not work as documented on the emulator (attributes 
and dates will be incorrect).</p>
<p>To access a file, you must
first retrieve the volume on which it resides using enumvols(). This function will enumerate
all volumes on the device - if the device does not support VFS, no volumes will be returned.
Once you have retrieved the volume id, you can use it to create and open files and directories.
To get a list of all the files in a directory, first open the directory with volopendir(),
then enumerate through the files and directories using direnum(). The get the files in the
root directory, call direnm(dirid, "/"). Unlike traditional operating systems, the Palm OS VFS support does not support a concept of
"current directory". Instead, all paths are fully specified for a given volume.</p>
<ul>
  <li><b>Volumes</b>
    <ul>
      <li><i>enumvols(int first, pointer pvolid)</i> - enumerates all the 
      volumes on the device, returning the volume id in the int pointed to by <i>
      pvolid</i>. Set <i>first</i> to true to enumerate the first volume, set it 
      to false for all subsequent calls. Returns 0 if there are no more volumes. You must close a volume when you have finished using it 
      by calling volclose().</li>
      <li><i>volclose(int volid)</i> - closes the given volume.</li>
      <li><i>volopenfile(int volid, string path, int mode, pointer fileid)</i> - 
      opens a file at the given <i>path</i>, using the specified <i>mode</i>, 
      returning the new id of the file in the int pointed to by <i>pfileid</i>. 
      Returns 0 on success. <i>mode</i> is a combination of the following flags: 
      vfsModeRead[2], vfsModeWrite[5], vfsModeReadWrite[7], vfsModeCreate[8], 
      vfsModeTruncate[16]. You must close the file when you have finished using 
      it by calling fileclose().</li>
      <li><i>volopendir(int volid, string path, pointer pdirid)</i> - opens a 
      directory at the given <i>path</i>, returning the new id of the directory in 
      the int pointed to by <i>pfileid</i>. Returns 0 on success. You must close 
      the directory when you have finished using it by calling dirclose().</li>
      <li><i>volcreatefile(int volid, string path)</i> - creates a new empty 
      file at the given <i>path</i>. Returns 0 on success.</li>
      <li><i>volcreatedir(int volid, string path)</i> - creates a new empty 
      directory at the given <i>path</i>. Returns 0 on success.</li>
      <li><i>voldelete(int volid, string path)</i> - deletes a file or empty 
      directory at the given <i>path</i>. Returns 0 on success.</li>
      <li><i>volrename(int volid, string path, string newname)</i> - renames a 
      file or directory specified by <i>path</i>. <i>newname</i> is the new name 
      of the file or directory without the path. Returns 0 on success.</li>