Properties
Now that you have an idea of what functionality the Winsock control provides, let's look at the properties it exposes. Table 14-1 contains a list of the properties available for affecting the control's behavior and for obtaining information about the control's state.
Property Name | Return Value | Read-Only? | Description |
BytesReceived | Long | Yes | Returns the number of bytes pending in the receive buffer. Use the GetData method to retrieve the data. |
LocalHostName | String | Yes | Returns the local machine name. |
LocalIP | String | Yes | Returns a string of the dotted decimal IP address of the local machine. |
LocalPort | Long | No | Returns or sets the local port to use. Specifying 0 for the port tells the system to randomly choose an available port. In general, only a client uses 0. |
Protocol | Long | No | Returns or sets the protocol for the control, which supports either TCP or UDP. The constant values to set are sckTCPProtocol and sckUDPProtocol, which correspond to 0 and 1, respectively. |
RemoteHost | String | No | Returns or sets the remote machine name. You can use either the string host name or the dotted decimal string representation. |
RemoteHostIP | String | Yes | Returns the remote machine's IP address. For TCP connections, this field is set upon a successful connection. For UDP operations, this field is set upon the DataArrival event, which then contains the sending machine's IP address. |
RemotePort | Long | No | Returns or sets the remote port to connect to. |
SocketHandle | Long | Yes | Returns a value that corresponds to the socket handle. |
State | Integer | Yes | Returns the state of the control, which is an enumerated type. See Table 14-2 for the socket state constants. |
After reading Chapter 1, you should be familiar with these basic properties. They are clearly analogous to the basic Winsock functions presented in the client/server examples discussed in that chapter. A few properties that don't relate well to the Winsock API do need to be set to use the control properly. First, the Protocol property needs to be set to tell the control which type of socket you're looking for—SOCK_STREAM or SOCK_DGRAM. The control performs the actual socket creation under the hood, and this property is the only control you have over it. The SocketHandle property can be read after a connection succeeds or after a server binds to wait for connections. This is useful if you want to pass the handle to other Winsock API functions imported from a DLL. The State property can be used to get information about what the control is currently doing. This is important because the control is asynchronous, and events can be fired at any time. Use this property to make sure that the socket is in a valid state for any subsequent operations. Table 14-2 contains the possible socket states and their meanings.
Constant | Value | Meaning |
sckClosed | 0 | Default. Closed. |
sckOpen | 1 | Open. |
sckListening | 2 | Listening for connections. |
sckConnectionPending | 3 | Connection request has arrived but has not completed yet. |
sckResolvingHost | 4 | Host name is being resolved. |
sckHostResolved | 5 | Host name resolution has completed. |
sckConnecting | 6 | Connection request started but has not completed. |
sckConnected | 7 | Connection completed. |
sckClosing | 8 | Peer has initiated a close. |
sckError | 9 | An error has occurred. |