NetStreams SocketStream

See also object creation information - ClassID/ProgID 

Overview | Reference


The SocketStream is the most important object in the NetStreams library. It implements the core WinSock functionality and provides an IStream interface to the outer world (and especially for the SFStream object from the newObjects ActiveX Pack1)  so data transfer can be performed. All the other objects in the library are intended mostly to control or query this object. 


method.gif (107 bytes) Socket Syntax:
bSuccess = object.Socket([af [, st [, proto]]])

When a SocketStream object is created it is uninitialized. To initialize it you need to call the Socket member and specify the address family, the socket type and the sub-protocol on which the object will work. Therefore this is the first member of the SocketStream object you should use before refering toany other method or property.

bSuccess - A Boolean value indicating the success or failure of the operation. If False (Failure) is returned the LastError property can be checked for the error text. 

af - optional. String or a numeric code. 

method.gif (107 bytes) Connect Syntax:
bSuccess = object.Connect(address)

Connects the client to a listening socket on the remote machine with the address specified.

address - is an initialized SocketAddress object.

IP V4/V6: The address should be initialized with IP address and a port number. It can be obtained after a name lookup if the NSMain.GetHost method is used.

IRDA: The address of the device and the ServiceName must be specified. The device address can be obtained by using IRDADeviceInfo object and the SocketStream's GetOption method (See the IRDADeviceInfo for more information how to do it).

method.gif (107 bytes) Bind Syntax:
bSuccess = object.Bind(address)

Binds the socket to the address specified. If the bind is successful True is returned and if not the method will return False and the LastError can be queried for the error text.

address - is an initialized SocketAddress object.

IP protocol: Usually the address should specify IP and a port number. However one of them or both can be zeros. If that case for a zero IP the socket will be bound to all the local machine IP interfaces. If the port is 0 a free port will be selected by the system. It can be queried through the SocketAddress property.

IRDA: The address should be zero, but the ServiceName must be set. That is the service name the other devices will try to connect to when they are looking for the service you provide. 


method.gif (107 bytes) Listen Syntax:
bSuccess = object.Listen([backlog])

Called after successful binding (see Bind) to an address. If successful this method puts the socket in a listening state and the incomming connection requests are queued for processing. The system queues a number of connection requests, to get one from the queue you must call the Accept method.

bSuccess - A Boolean value indicating the success or failure of the operation. If False (Failure) is returned the LastError property can be checked for the error text. 

backlog - optional. Numeric value specifying the size of the queue for the incoming connection requests. The allowed maximum may very from protocol to protocol and an the OS. In most cases applications written with maximum portability in mind should skip it and rely on the defaults in order to avoid the need of adjustment for each OS/protocol.

method.gif (107 bytes) Accept Syntax:
Set new_socket = object.Accept

Returns a newly accepted connection. Can be called after the socket is bound (Bind) and is in listening mode (Listen). The returned object is a SocketStream object as well. It is connected to the connecting party (the client) and can be used immediately for data transfer. It can be queried also for the addresses of the other side (PeerAddress) and the local address (SocketAddress).

method.gif (107 bytes) Shutdown Syntax:
bSuccess = object.Shutdown(how)

This method is provided for completeness. However it is rarely needed in Windows and maybe used only in some cases where more detailed control over the disconnection process is required. Most applications should just Close the SocketStream object skipping this method call.

bSuccess - indicates the success of the operation (Boolean value).

how - specifies flag or flags indicating how the shutdown will occur. See MSDN and MS SDK for the flag values - they are passed directly to the WinSock by this method.

method.gif (107 bytes) Close Syntax:
bSuccess = object.Close

Closes the socket. If it is connected a disconnection will occur before that. By default all the sockets are configured to disconnect gracefully when closed, so you can call this member to drop a connection and skip any usage of the Shutdown method.

The returned success/failure Boolean value is of very little use as it is not much you can do if an error occurs - if this happens it is a failure in the machine's socket stack.

method.gif (107 bytes) Select Syntax:
v = object.Select( [timeout [, r [, w [, e]]]])

Obtains information about the state of the SocketStream object. Rarely needed in blocking mode, but vital in non-blocking mode. 


timeout - (default 0). Timeout in seconds specifying how long the system may wait to complete the state obtaining operation. 

r, w, e - all are Boolean and True by default (if omitted). They specify which characteristics should be obtained - r - ready to read, w - ready to write, e - error state.

The return result is a flag set which can be processed by using bitwise logical operations or can be feed into a SocketSelectHelper object which provides (especially scripting applications) with more convenient and human readable way to determine them. The bits indicating each of the above states are as follows:
bit 0 - error
bit 1 - write
bit 2 - read


Note that the names of these states were defined long ago and they do not exactly represent the applications for which they are used most frequently today. It is recommended to read the MSDN chapters for them. Here is short explanation of what they indicate in various cases:


  • If Listen has been called and a connection is pending, Accept will succeed.
  • Data is available for reading.
  • Connection has been closed/reset/terminated.


  • If processing a Connect call (non-blocking), connection has succeeded.
  • Data can be sent.


  • If processing a Connect call (non-blocking), connection attempt failed.
method.gif (107 bytes) GetOption Syntax:
bSuccess = object.GetOption(optObject)

Queries the socket for a socket or a protocol specific option (see the supported options on the SockOpt object page).

The return value indicates the success (True)/failure (False) state of the operation. In case of failure the LastError property can be queried for the error text.


Both SetOption and GetOption use a SockOpt holder object which must be initialized before the call. The caller fills in the option parameters (and values if SetOption will be used) and passes the option to the method. When getting option after successful call the caller can read the result from the same SockOpt object which has been passed to the call - its value will be set to the result returned by the WinSock internally. More details can be found in the description of the SockOpt object.

method.gif (107 bytes) SetOption Syntax:
bSuccess = object.SetOption(optObject)

Sets a socket or a protocol specific option (see the supported options on the SockOpt object page).

The return value indicates the success (True)/failure (False) state of the operation. In case of failure the LastError property can be queried for the error text.

See the remarks above (in the GetOption description)

Blocking Syntax:
object.Blicking = value
v = object.Blocking

Gets/Sets the mode of the SocketStream object. By default the SocketStreams are created in blocking mode (the property will return True if not set before). If you want to change the SocketStream to non-blocking you should set this property to False. The moment when this can be done may vary depending on the protocol and family, but generally it may be assumed that such action should be performed before connection or binding.

InBufferSize Syntax:
v = object.InBufferSize

Returns the size (in bytes) of the receive buffer allocated by the system for this object.

OutBufferSize Syntax:
v = object.OutBufferSize

Returns the size (in bytes) of the send buffer allocated by the system for this object.

LastError Syntax:
v = object.LastError

Returns the error text for the last error. The value is meaningful only after an error indicated by the return result of one of the object's methods. If called after a successful operation the property may still hold the text for the previous error - do not use this property to determine the success of the last otperation.

Address Syntax:
Set addr = object.Address

Returns a SocketAddress object holding a copy of the address to which the object has been connected or bound. This is a copy of the address you have passed to Connect or Bind method and NOT the actual address of the SocketStream object! To obtain the actual address use the SocketAddress property.

PeerAddress Syntax:
Set addr = object.PeerAddress

Returns a SocketAddress object filled with the address of the peer (the other side of the connection). The property should be read only on a connected SocketObject. Otherwise an error will occur because the operationis not applicable.

SocketAddress Syntax:
Set addr = object.SocketAddress

Returns a SocketAddress object filled with this address of this SocketStream object as reported bythe WinSock. This property is particularly useful when you want the system to find a free port for your server. Reading it you will be able to find out the actual port number allocated for you. In contrast to the Address property which returns just the address recorded from a Connect or a Bind call this property queries the object for its actual state. 

AddressFamily Syntax:
v = object.AddressFamily

Returns the address family for which the SocketStream as been initialized (see the Socket method). The property returns the numeric constant - not the key name of the address family.

Protocol Syntax:
v = object.Protocol

Returns the protocol identifier constant for the protocol for which the SocketStream has been initialized (see Socket method).

ProtocolName Syntax:
v = object.ProtocolName

Returns the protocol key name identifier for the protocol for which the SocketStream has been initialized (see Socket method).

Type Syntax:
v = object.Type

Returns the type identifier numeric constant for the socket type for which the SocketStream has been initialized during a previous call to the Socket method.

TypeName Syntax:
v = object.TypeName

Returns the type identifier key name for the socket type for which the SocketStream has been initialized during a previous call to the Socket method.

Valid Syntax:
b = object.Valid

Boolean read only property that indicates if the socket object is valid. See also property InvalidObjectsOnError.

InvalidObjectsOnError Syntax:
b = object.InvalidObjectsOnError
object.InvalidObjectsOnError = b

Boolean read/write property. If set to True no script errors will occur on socket or network errors. Default is False - script error will be raised in case of socket or network error. This is especially useful for languages like JScript (V 3.X) where no proper exception/error handling is available. In such cases you may want to se this to True and check if the operation is successful using other ways.

For example when this property is set to True Accept will return socket always, but if it is not successful the returned SocketStream object will not be valid (the Valid property will indicate this). The same behavior is applied to the addressing properties PeerAddress and SocketAddress and in various other circumstances where the error is not fatal system failure but a network or socket error. So the behavior of the ScoketStream object with this property set to True involves almost no COM/script exceptions. Errors may be returned only if the condition dos not allow continued processing - such as out of memory errors. Except for JScript 3.X this can be convenient for developers who prefer processing errors and exceptions  in the normal code flow instead of using exception handling techniques. 

LastErrorCode Syntax:
v = object.LastErrorCode

Long integer read only property. Returns the last error code which is -1 for all the COM and internal object errors and the WinSock's WSALastError code if the error is reported by the WinSock. This can be especially useful when used with non-Blocking sockets where the error value may have important meaning. With blocking sockets almost always the error code have only informative meaning and can be used to generate more precise error texts, but aside of that it has a little importance for the code flow. The positive error codes are true WinSock error values which can be found in MSDN.


newObjects Copyright 2001-2006 newObjects [ ]