| Property Name | Description |
|---|---|
| AutoResolve | Determines if host names and IP addresses are automatically resolved. |
| Blocking | Gets and sets the blocking state of the class instance. |
| HostAddress | Gets and sets the IP address of the remote host. |
| HostName | Gets and sets the name of the remote host. |
| IsBlocked | Determine if the class instance is blocked performing an operation. |
| IsConnected | Determine if the class instance is connected to a remote host. |
| IsReadable | Determine if data can be read from the remote host without blocking. |
| IsWritable | Determine if data can be sent to the remote host without blocking. |
| LastError | Gets and sets the last error that occurred on the class instance. |
| LastErrorString | Return a description of the last error to occur. |
| LocalAddress | Return the IP address of the local host. |
| LocalName | Return the name of the local host. |
| RemotePort | Gets and sets the port number for a remote connection. |
| Secure | Set or return if a connection to the server is secure. |
| Status | Return the current status of the session. |
| ThrowError | Enable or disable error exceptions being generated by class methods. |
| Timeout | Gets and sets the amount of time until a blocking operation fails. |
| Trace | Enable or disable socket function level tracing. |
| TraceFile | Specify the socket function trace output file. |
| TraceFlags | Gets and sets the socket function tracing flags. |
| Version | Return the current version of the class library. |
Many of the SocketWrench .NET class properties are similar to those used by the ActiveX control. Developers are familiar with previous versions of SocketWrench should find that this significantly reduces the amount of time required to port an existing application to the .NET framework. It is recommended that you also review the Technical Reference material for specific information about a particular property.
The AutoResolve property controls how host names are resolved by the class whenever the HostName or HostAddress properties are set. By default, the property is set to false, which means that the class instance does not attempt to resolve the host name until a connection attempt is made. If the property is set to true, then the class will immediately attempt to resolve the host name into an IP address. Note that this can cause the class to block for several seconds and negatively affect the performance of your program. In most cases, this property should be set to false.
The Blocking property determines whether or not the class operates in blocking (synchronous) mode or non-blocking (asynchronous) mode. In blocking mode, the class waits for a given operation to complete before returning control to your application and executing the next statement. In non-blocking mode, control is immediately returned to the program without waiting for the operation to complete. In this case, events are used to notify the application that a specific operation has completed.
In general, using the class in blocking mode means that your code is going to be structured in a top-down fashion. For example, when establishing a connection with a remote system, your program will block until the connection has completed or has timed out. In non-blocking mode, your code is event driven and must implement event handlers to process those event notifications.
It is recommended that you only establish a non-blocking connection when you understand the implications of doing so and it is required by your application. If you require multiple instances of the class to establish connections to different servers, it is preferable to create a multithreaded application rather than attempt to use multiple instances of the class in a single thread.
The HostAddress property is used to specify the IP address of a remote host to connect to. The address should be given in dot notation, which is four numbers separated by periods (e.g.: 192.168.0.10). If the AutoResolve property is set to true, setting this property will force the class to immediately resolve the address into a host name. Note that if you attempt to set this property to the value of a host name, an exception will be thrown indicating that the property value is invalid.
The HostName property is used to specify the name of a remote host to connect to. This property will accept either host names or IP addresses. If an IP address is specified, then setting this property is similar to setting the HostAddress property. If the AutoResolve property is set to true, setting this property will force the class to immediately resolve the host name into an IP address. The value of this property is used as the default host name when the Connect method is called.
The IsBlocked property returns true if the class instance is currently performing a blocking operation. This can be used in conjunction with the Status property to determine if the class can be used to issue a command to the server or perform some other operation. When the IsBlocked property returns false and the Status property returns a value of zero or one, the class instance is in either an inactive or idle state. If the program attempts to perform another operation while a blocking operation is in progress, the error errorOperationInProgress is returned.
The IsConnected property returns true if a connection has been made with a remote server, otherwise it will return false. The property is read-only, and any attempt to set it to a value will result in an error. To establish a connection, refer to the Connect method.
The IsReadable property returns true if there is data available to read using the Read method. If the property returns false, then there is no data available to be read. In this case, if the Blocking property is set to true, calling the Read method will cause the class to block until data arrives or the timeout period is exceeded; otherwise, it will fail and return the error stErrorOperationWouldBlock. Note that this property can only be used to determine if there is data available to be read, not the amount of data.
The IsWritable property returns true if the class can successfully write data using the Write method. If the property returns false, then the socket's internal buffers are full and cannot accept any more data until the remote host reads some of the data that has already been written. In this case, if the Blocking property is set to true, the Write method will cause the class to block until the data can be written or the timeout period is exceeded; otherwise, it will fail and return the error stErrorOperationWouldBlock. Note that this property can only be used to determine if some data can be written, not the amount of data.
The LastError property returns a numeric value which identifies the last error that occurred. This property may be set to zero, which will clear the last error code. Note that setting this property to a non-zero value will have the effect of raising that error, which must be handled by the application. Refer to the Technical Reference for a complete list of error codes and their description.
The LastErrorString property returns a description of the last error that occurred, and corresponds to the value of the LastError property. This property is typically used by an application to display a message box to the user or include information about the error in a log file. Note that the error description will be in English, regardless of the current locale settings.
The LocalAddress property returns the IP address of the local host. Note that if the system is behind a router which uses Network Address Translation (NAT) then the IP address returned will be the address of the system on the local network, not the external WAN address assigned to the router.
The LocalName property returns the fully qualified domain name of the local host, if that information is available. If the class is unable to determine the domain name for the local system, then it will return the machine name as it was configured in the Windows operating system.
The RemotePort property is used to specify the port number used to establish a connection with the remote host. Valid port numbers are in the range of 1 through 65535, and assigning the property a value greater than this will result in an error. This property value is used as the default port number when the Connect method is called.
The Secure property determines if the class should establish a secure connection to the server. The default value for this property is false, which specifies that a standard connection should be established. If this property is set to true, then the class will attempt to establish a secure connection using the Secure Sockets Layer (SSL) or Transport Layer Security (TLS) protocols. Attempting to set this property to true will cause the class to throw an exception if SocketWrench cannot establish a secure session.
The Status property returns a numeric value which identifies the current state of the class instance. A value of zero indicates that no connection has been established with the class. A value of one indicates that the class is in an "idle" state, waiting to process the next request or send a command to the server. Values greater than one indicates that instance of the class is actively performing some operation. Refer to the Technical Reference documentation to determine what each state value means.
The ThrowError property is used to determine how errors are reported by the class when calling a method. The default value is false, which specifies that errors should be returned as values from the method call and the class instance should not throw an exception. If this property is set to true, then methods will throw an exception whenever an error is encountered. This can be useful if you want to implement an exception handler for any error conditions rather than checking the return value from each method call.
The Timeout property used to determine how long the class instance will wait for a blocking operation to complete before returning control to the application. If the property is set to a value of zero, then the class will wait indefinitely for a blocking operation to complete, except when establishing a connection. The default value for the property in most cases is 60 seconds. The Timeout property is only used when the Blocking property is set to true.
The Trace property is used to enable or disable the trace logging features of the class. When the property is set to true, that instance of the class will record all of the networking function calls that it makes, and depending on the trace level, the data exchanged between the client and server. To enable trace logging, you must include the trace library SocketTools.TraceLog.dll with your application. If this library cannot be loaded, the value of the Trace property value will be ignored.
The TraceFile property is used to specify the name of a file that will contain the trace logging data generated when the Trace property is set to true. This property should be set prior to setting the Trace property.
The TraceFlags property is used to specify the amount of information that is recorded by the trace logging facility. The default value traceDefault specifies that all of the networking function calls should be logged, along with their arguments and return values (this is the same as specifying the traceInfo option). The following values are used:
| Trace Option | Description |
|---|---|
| traceInfo | All function calls are written to the trace file, including information about successful calls made to the networking library. This is the default value. |
| traceError | Only those function calls which fail are recorded in the trace file. Functions which are successful or only return values which indicate a warning are not logged. |
| traceWarning | Only those function calls which fail, or return values which indicate a warning, are recorded in the trace file. Successful function calls are not logged. |
| traceHexDump | All functions calls are written to the trace file, plus all the data that is sent or received is displayed in both ASCII and hexadecimal format. This is useful for examining the actual byte stream that is exchanged between the application and the remote host. |
The Version property returns the current version of the class instance as a string. This can be used by the application to check that the correct version of the class has been installed on the local system.