wxJavaScript

back to io 

wxSocketBase

^{generated from ../src/mod_io/sockbase.cpp}

wxSocketBase is the property class for all socket-related objects, and it defines all basic IO functionality.

Constants

wxSocketError

Name	Description
NOERROR	No error happened.
INVOP	Invalid operation.
IOERR	Input/Output error.
INVADDR	Invalid address.
INVSOCK	Invalid socket (uninitialized).
NOHOST	No corresponding host.
INVPORT	Invalid port.
WOULDBLOCK	The socket is non-blocking and the operation would block.
TIMEDOUT	The timeout for this operation expired.
MEMERR	Memory exhausted.

wxSocketError is ported to JavaScript as a separate class. Note that this class doesn't exist in wxWidgets.

wxSocketEventType

Name	Description
INPUT	There is data available for reading.
OUTPUT	The socket is ready to be written to.
CONNECTION	Incoming connection request (server), or successful connection establishment (client).
LOST	The connection has been closed.

wxSocketEventType is ported to JavaScript as a separate class. Note that this class doesn't exist in wxWidgets.

wxSocketFlags

Name	Description
NONE	Normal functionality.
NOWAIT	Read/write as much data as possible and return immediately.
WAITALL	Wait for all required data to be read/written unless an error occurs.
BLOCK	Block the GUI (do not yield) while reading/writing data.
REUSEADDR	Allows the use of an in-use port (wxServerSocket only)

wxSocketFlags is ported to JavaScript as a separate class. Note that this class doesn't exist in wxWidgets.

Properties

Name	Type	Description
connected	Boolean	Returns true if the socket is connected.
data	Boolean	This property waits until the socket is readable. This might mean that queued data is available for reading or, for streamed sockets, that the connection has been closed, so that a read operation will complete immediately without blocking (unless the wxSocketFlags.WAITALL flag is set, in which case the operation might still block).
disconnected	Boolean	Returns true if the socket is disconnected.
error	Boolean	Returns true if an error occurred in the last IO operation.
lastCount	Integer	Returns the number of bytes read or written by the last IO call
lastError	wxSocketError	Returns the last wxSocket error. Please note that this property merely returns the last error code, but it should not be used to determine if an error has occurred (this is because successful operations do not change the lastError value). Use error first, in order to determine if the last IO call failed. If this returns true, use lastError to discover the cause of the error.
ok	Boolean	Returns true if the socket is initialized and ready and false in other cases. Remark/Warning: For wxSocketClient, ok won't return true unless the client is connected to a server. For wxSocketServer, ok will return true if the server could bind to the specified address and is already listening for new connections. ok does not check for IO errors; use error instead for that purpose.

Methods

close

close()
 

This function shuts down the socket, disabling further transmission and reception of data; it also disables events for the socket and frees the associated system resources. Upon socket destruction, close is automatically called, so in most cases you won't need to do it yourself, unless you explicitly want to shut down the socket, typically to notify the peer that you are closing the connection.

Remark/Warning: Although close immediately disables events for the socket, it is possible that event messages may be waiting in the application's event queue. The application must therefore be prepared to handle socket event messages even after calling close.

discard

discard()
 

This function simply deletes all bytes in the incoming queue. This function always returns immediately and its operation is not affected by IO flags. Use lastCount to verify the number of bytes actually discarded. If you use error, it will always return false.

interruptWait

interruptWait()
 

Use this method to interrupt any wait operation currently in progress. Note that this is not intended as a regular way to interrupt a wait call, but only as an escape mechanism for exceptional situations where it is absolutely necessary to use it, for example to abort an operation due to some exception or abnormal problem. InterruptWait is automatically called when you close a socket (and thus also upon socket destruction), so you don't need to use it in these cases.

notify

notify(Flag)
 

Name	Type	Default	Description
Flag	Boolean

According to the Flag value, this function enables or disables socket events. If Flag is true, the events configured with setNotify will be sent to the application. If Flag is false; no events will be sent.

peek

peek(Buffer) : wxSocketBase
 

Name	Type	Default	Description
Buffer	wxMemoryBuffer

This function peeks a buffer (with the given size of the buffer) from the socket. Peeking a buffer doesn't delete it from the socket input queue. Use lastCount to verify the number of bytes actually peeked. Use error to determine if the operation succeeded. Returns a reference to the current object.

Remark/Warning: The exact behaviour of peek depends on the combination of flags being used.

read

read(Buffer) : wxSocketBase
 

Name	Type	Default	Description
Buffer	wxMemoryBuffer

This function reads a buffer (with the given size of the buffer) from the socket. Use lastCount to verify the number of bytes actually read. Use error to determine if the operation succeeded. Returns a reference to the current object.

Remark/Warning: The exact behaviour of read depends on the combination of flags being used.

readMsg

readMsg(Buffer) : wxSocketBase
 

Name	Type	Default	Description
Buffer	wxMemoryBuffer

This method reads a buffer sent by writeMsg on a socket. If the buffer passed to the function isn't big enough, the remaining bytes will be discarded. This function always waits for the buffer to be entirely filled, unless an error occurs. Use lastCount to verify the number of bytes actually read. Use error to determine if the operation succeeded. Returns a reference to the current object.

Remark/Warning: readMsg will behave as if the wxSocketFlag.WAITALL flag was always set and it will always ignore the wxSocketFlag.NOWAIT flag.

restoreState

restoreState()
 

This function restores the previous state of the socket, as saved with saveState. Calls to saveState and restoreState can be nested.

saveState

saveState()
 

This method saves the current state of the socket in a stack. Socket state includes flags, as set with flags, event mask, as set with setNotify and notify, user data, as set with clientData. Calls to saveState and restoreState can be nested.

setTimeout

setTimeout(Seconds)
 

Name	Type	Default	Description
Seconds	Integer

This function sets the default socket timeout in seconds. This timeout applies to all IO calls, and also to the Wait family of functions if you don't specify a wait interval. Initially, the default timeout is 10 minutes.

unread

unread(Buffer) : wxSocketBase
 

Name	Type	Default	Description
Buffer	wxMemoryBuffer

This function unreads a buffer. That is, the data in the buffer is put back in the incoming queue. This function is not affected by wxSocketFlag. Use lastCount to verify the number of bytes actually read. Use error to determine if the operation succeeded. Returns a reference to the current object.

wait

wait(Seconds = -1, 
     MilliSeconds = 0) : Boolean
 

Name	Type	Default	Description
Seconds	Integer	-1
MilliSeconds	Integer	0

This function waits until any of the following conditions is true:

• The socket becomes readable.
• The socket becomes writable.
• An ongoing connection request has completed (wxSocketClient only)
• An incoming connection request has arrived (wxSocketServer only)
• The connection has been closed.

Note that it is recommended to use the individual wait functions to wait for the required condition, instead of this one.
Returns true when any of the above conditions is satisfied, false if the timeout was reached.

waitForLost

waitForLost(Seconds = -1, 
            MilliSeconds = 0) : Boolean
 

Name	Type	Default	Description
Seconds	Integer	-1
MilliSeconds	Integer	0

This function waits until the connection is lost. This may happen if the peer gracefully closes the connection or if the connection breaks. Returns true if the connection was lost, false if the timeout was reached.

waitForRead

waitForRead(Seconds = -1, 
            MilliSeconds = 0) : Boolean
 

Name	Type	Default	Description
Seconds	Integer	-1
MilliSeconds	Integer	0

This function waits until the socket is readable. This might mean that queued data is available for reading or, for streamed sockets, that the connection has been closed, so that a read operation will complete immediately without blocking (unless the wxSocketFlag.WAITALL flag is set, in which case the operation might still block). Returns true if the socket becomes readable, false on timeout.

waitForWrite

waitForWrite(Seconds = -1, 
             MilliSeconds = 0) : Boolean
 

Name	Type	Default	Description
Seconds	Integer	-1
MilliSeconds	Integer	0

This function waits until the socket becomes writable. This might mean that the socket is ready to send new data, or for streamed sockets, that the connection has been closed, so that a write operation is guaranteed to complete immediately (unless the wxSocketFlag.WAITALL flag is set, in which case the operation might still block) Returns true if the socket becomes writable, false on timeout.

write

write(Buffer) : wxSocketBase
 

Name	Type	Default	Description
Buffer	wxMemoryBuffer

This function writes a buffer (with the given size of the buffer) to the socket. Use lastCount to verify the number of bytes actually written. Use error to determine if the operation succeeded. Returns a reference to the current object.

Remark/Warning: The exact behaviour of write depends on the combination of flags being used.

writeMsg

writeMsg(Buffer) : wxSocketBase
 

Name	Type	Default	Description
Buffer	wxMemoryBuffer

This function writes a buffer to the socket, but it writes a short header before so that readMsg knows how much data should it actually read. So, a buffer sent with writeMsg must be read with readMsg. This function always waits for the entire buffer to be sent, unless an error occurs. Use lastCount to verify the number of bytes actually read. Use error to determine if the operation succeeded. Returns a reference to the current object.

Remark/Warning: writeMsg will behave as if the wxSocketFlag.WAITALL flag was always set and it will always ignore the wxSocketFlag.NOWAIT flag.