Updated Aug 18, 2008 by soubok
Labels:	doc

jsio

jsio module

- source - main -

jsio module

This module is based on Netscape Portable Runtime (NSPR) that provides a platform-neutral API for system level and libc like functions. NSPR API is used in the Mozilla client, many of Netscape/AOL/iPlanet's and other software offerings.

Static functions

_integer Pool( descriptorArray [, timeout = undefined ] )

This function listen for a readable, writable or exception event on each descriptor in descriptorArray. When an event occurs, the function tries to call the corresponding property (function) on the descriptor.
The function returns the number of events that occurs or 0 if the function timed out.
note:

The property is NOT cleared by the function. If you want to stop receiving an event, you have to remove the property by yourself. eg. delete socket1.writable.
The second argument, timeout, defines the number of milliseconds the function has to wait before returning if no event has occured. timeout can be undefined OR omited, in this case, no timeout is used.
beware:

No timeout means that the function will wait endless for events.
example:

socket1.readable = function(soc) { Print( soc.Recv(); ) } var count = Poll( [socket1, socket2], 1000 ); if ( count == 0 ) Print( 'Nothing has been recived' );

_boolean IsReadable( descriptor )

Returns true if the descriptor can be read without blocking.

_boolean IsWritable()

Returns true if the descriptor can be write without blocking.

_integer IntervalNow()

Returns the milliseconds value of NSPR's free-running interval timer.

_integer UIntervalNow()

Returns the microseconds value of NSPR's free-running interval timer.

Sleep( milliseconds )

Sleeps milliseconds milliseconds.

_string GetEnv( name )

Retrieve the value of the given environment variable.

_string GetRandomNoise( size )

Provides, depending on platform, a random value. The length of the random value is dependent on platform and the platform's ability to provide a random value at that moment.
beware:

Calls to GetRandomNoise() may use a lot of CPU on some platforms. Some platforms may block for up to a few seconds while they accumulate some noise. Busy machines generate lots of noise, but care is advised when using GetRandomNoise() frequently in your application.
note:

NSPR API

WaitSemaphore( semaphoreName )

Tests the value of the semaphore. If the value of the semaphore is > 0, the value of the semaphore is decremented and the function returns. If the value of the semaphore is 0, the function blocks until the value becomes > 0, then the semaphore is decremented and the function returns.
note:
The "test and decrement" operation is performed atomically.

PostSemaphore( semaphoreName )

Increments the value of a specified semaphore.

_value CreateProcess( path [, argv [, waitExit ]] )

This function starts a new process optionaly using the array argv for arguments or <undefined>. If waitExit is true, the function waits the end of the process and returns its exit code. If waitExit is not true, the function immediately returns an array that contains an input pipe and an output pipe to the current process stdin and stdout.

Static properties

_string hostName

Is the host name with the domain name (if any).

_integer physicalMemorySize

Is the amount of physical RAM in the system in bytes.

_Object systemInfo

Returns an object that contains an architecture, a name and a release property.

_integer processPriority

Is the current process priority among the following values:
-1: low
0: normal
1: high
2: urgent

_string currentWorkingDirectory

is the current working directory.

jsio::Descriptor class

- src - top -

Methods

Close()

Close the descriptor.

_value Read( amount )

Read amount bytes of data from the current descriptor. If amount is ommited, the whole available data is read. If the descriptor is exhausted (eof or disconnected), this function returns <undefined>.
beware :

This function returns a Blob or a string literal as empty string.

_string Write( data )

If the whole data cannot be written, Write returns that have not be written.

Sync()

Sync any buffered data for a fd to its backing device.

Properties

available

Determine the amount of data in bytes available for reading on the descriptor.

type

see constants.

closed

Is true if the file descriptor has been closed.
beware:

Do not confuse with disconnected.

jsio::Directory class

- src - top -

This class manages directory I/O Functions.

constructor( directoryName )

Creates a new Directory object.
arguments:

_string directoryName

Methods

_this Open()

Open the directory.

Close()

Close the specified directory.

_string Read( [, flags = Directory.SKIP_NONE ] )

Reads an item of the current directory and go to the next.

arguments:

_enum flags: specifies how special files are processed.
return value:

returns a single directory item.

Make()

Create the directory given in the constructor.

_boolean Remove()

Removes the directory given in the constructor.
return value:

returns <false> If the directory is not empty else it returns <true>.

Properties

exist

Check if the directory exists.

name

Returns the name of the directory.

Static functions

_Array List( dirName [, flags = Directory.SKIP_DOT] )

Read all entries of a directory at once.
arguments:

_string dirName: is the path of the directory.
_enum flags: specifies how special files are processed.
return value:

returns all entries in the directory name.
note:

This function supports additional flags: Directory.SKIP_FILE, Directory.SKIP_DIRECTORY, Directory.SKIP_OTHER
example:

LoadModule('jsstd'); LoadModule('jsio'); Print( Directory.List('.').join('\n'), '\n' );

Constants

Directory.SKIP_NONE

Do not skip any files.

Directory.SKIP_DOT

Skip the directory entry "." representing the current directory.

Directory.SKIP_DOT_DOT

Skip the directory entry ".." representing the parent directory.

Directory.SKIP_BOTH

Skip both "." and ".." ( same as Directory.SKIP_DOT | Directory.SKIP_DOT_DOT )

Directory.SKIP_HIDDEN

Skip hidden files. On Windows platforms and the Mac OS, this value identifies files with the "hidden" attribute set. On Unix platform, this value identifies files whose names begin with a period (".").

Example

var dir = new Directory( 'c:/tmp' );
dir.Open();
for ( var entry; ( entry = dir.Read() ); ) {

   var file = new File(dir.name+'/'+entry);
   Print( entry + ' ('+ file.info.type +')', '\n');
}

Example

function RecursiveDir(path) {
   var testList = [];
   (function(path) {
      var dir = new Directory(path);
      dir.Open();
      for ( var entry; ( entry = dir.Read(Directory.SKIP_BOTH) ); ) {
         
         var file = new File(dir.name+'/'+entry);
         switch ( file.info.type ) {
            case File.FILE_DIRECTORY:
               arguments.callee(file.name);
               break;
            case File.FILE_FILE:
               testList.push(file.name);
               break;
         }
      }
      dir.Close();
   })(path);
   return testList;
}

Print( RecursiveDir('jshost').join('\n') );

jsio::File class ^{jsio::Descriptor}

- src - top -

constructor( fileName )

Methods

_this Open( flags [, mode] )

Open a file for reading, writing, or both.
flags is either a combinaison of open mode constants or a string that contains fopen like flags (+, r, w, a).
The functions returns the file object itself (this), this allows to write things like: new File('foo.txt').Open('r').Read();

_integer Seek( [ offset = 0 [, whence = File.SEEK_SET ] ] )

Moves read-write file offset.

_integer Delete()

Delete a file from the filesystem. The operation may fail if the file is open.

Lock( state )

Lock or unlock a file for exclusive access. state can be <true> or <false>.

Move( directory )

Move the file to another directory.

Properties

_integer position

Get or set the current position of the file pointer. Same as Seek() function used with SEEK_SET.

_string content

Get or set the content of the file. If the file does not exist, content is <undefined>. Setting content with <undefined> deletes the file.

_string name

Contains the name of the file. Changing this value will rename or move the file.

_boolean exist

Contains true if the file exists.

_Object info

This property works with opened and closed files. Contains an object that has the following properties:
type : Type of file.
size : Size, in bytes, of file's contents.
creationTime : Creation time (elapsed milliseconds since 1970.1.1).
modifyTime : Last modification time (elapsed milliseconds since 1970.1.1).
note:

Time is relative to midnight (00:00:00), January 1, 1970 Greenwich Mean Time (GMT).
beware:

File time resolution depends of hte underlying filesystem.
eg. the resolution of create time on FAT is 10 milliseconds, while write time has a resolution of 2 seconds and access time has a resolution of 1 day.
example:

var f = new File('test.txt'); f.content = '123'; Print( new Date( f.info.modifyTime ) );

Static properties

_File stdin

Is a jsio::File that represents the standard input.

_File stdout

Is a jsio::File that represents the standard output.

_File stderr

Is a jsio::File that represents the standard error.

Constants

Open mode

File.RDONLY
File.WRONLY
File.RDWR
File.CREATE_FILE
File.APPEND
File.TRUNCATE
File.SYNC
File.EXCL

Seek mode

File.SEEK_SET
File.SEEK_CUR
File.SEEK_END

info.type

File.FILE_FILE
File.FILE_DIRECTORY
File.FILE_OTHER

Native Interface

IStreamRead: Read the file as a stream.

Example

LoadModule('jsstd');
LoadModule('jsio');

try {

   var file = new File('file_test.txt');
   if ( file.exist ) {
      file.Open( File.RDONLY );
      Print( 'file content:\n' + file.Read() );
      file.Close();
   }

} catch ( ex if ex instanceof IoError ) {

   Print( 'IOError: ' + ex.text, '\n' );
} catch( ex ) {

   throw ex;
}

jsio::MemoryMapped class

- src - top -

constructor( file )

Creates a new memory-mapped object using the given opened file descriptor.
arguments:

_File file: any opened file descriptor.

Properties

file

is the file descriptor used to construct this object.

Native Interface

IBufferGet

Example

var f = new File('directory.cpp');
f.Open("r");
var m = new MemoryMapped(f);
Print(m);

jsio::Pipe class

- src - top -

jsio::Semaphore class

- src - top -

jsio::SharedMemory class

- src - top -

This class manages shared memory between two or more process.

constructor( name, size [, mode] )

Creates a named shared memory area of size bytes using mode linux-like rights.

Methods

Write( data [, offset] )

Write data at offset in the shared memory.

_string Read( length [, offset] )

Read length bytes from offset in the shared memory.

Clear()

Clears the content of the shared memory.

Close()

Close the shared memory.

Properties

_string content

Read or write the whole content of the shared memory. Setting <undefined> as value clears the memory area.

Native Interface

IBufferGet

Exemple

LoadModule('jsstd');
LoadModule('jsio');

var mem1 = new SharedMemory( 'mytest', 100 );
mem1.Write('foo');

var mem2 = new SharedMemory( 'mytest', 100 );
Print( mem2.Read(3), '\n' );

jsio::Socket class ^{jsio::Descriptor}

- src - top -

Socket class is used to create a non-blocking TCP socket.

constructor( = Socket.TCP )

Type can be Socket.TCP or Socket.UDP.

Methods

Shutdown( [ what ] )

Shut down part of a full-duplex connection on a socket.
if what is <true>, further receives will be disallowed.
if what is <false>, further sends will be disallowed.
if what is ommited or <undefined>, further sends and receives will be disallowed

Bind( port [, ip] )

Bind an ip address to a socket. ip is the address to which the socket will be bound. If address is ommited, any address is will match.

Listen( [ backlogSize = 8 ] )

Listen for connections on a socket. backlogSize specifies the maximum length of the queue of pending connections.

_Socket Accept()

Accept a connection on a socket. This function returns a connected jsio::Socket.

_this Connect( host, port [, timeout] )

Initiate a connection on a socket.

_string SendTo( host, port, string )

Send a specified number of bytes from an unconnected socket. See. Static functions.

_string RecvFrom()

Receive all data from socket which may or may not be connected. See. Static functions.

TransmitFile( fileDescriptor [, close [, headers [, timeout]]] )

Sends a complete file pointed by fileDescriptor across a socket.
headers is a string that contains the headers to send across the socket prior to sending the file.
Optionally, close flag specifies that transmitfile should close the socket after sending the data.
timeout is the time limit for completion of the transmit operation.
note:

This function only works with blocking sockets.

Properties

connectContinue

Test if a nonblocking connect has completed. Is <true> if the socket is connected.
Is <undefined> if the operation is still in progress.
Is <false> if the connection is refused.