Totally Objects - Socket Set - Version 5.5 [1.0]

Introduction

This document explains how to use the Socket Set product from Totally Objects for IBM's VisualAge for Smalltalk. The product provides tools that enable you to add TCP/IP capabilities to your applications without getting tied down with the complexities of sockets programming. Some high level tools are included to do everyday tasks such as sending and receiving email (SMTP + POP3 with attachments) or uploading and downloading files (FTP).

The most valuable aspect of the product is the ease in which servers can be built. You specify a port to which the server should listen and a block to be executed for each client that connects: the threads are managed for you so the connections appear asynchronous.

Installing the Socket Set

This Totally Objects product has been packaged as three configuration maps. To import them into your library select 'Browse Configuration Maps' from the 'Tools' menu of the 'System Transcript'. In the 'Configuration Maps Browser' select 'Import...' from the 'Names' menu and select the file tobss5-5_1-0-*.dat. You should then select the three configuration maps contained within this file:

• 'Totally Objects, Socket Set - Base', Version 5.5 [1.0.*] - Contains the base classes.
• 'Totally Objects, Socket Set - Parts', Version 5.5 [1.0.*] - Contains the edit and runtime parts.
• 'Totally Objects, Socket Set - Parts Examples', Version 5.5 [1.0.*] - Contains some example windows incorporating the parts.

To load the configuration maps into your image select each of them in the 'Configuration Maps Browser' select 'Load With Required Maps' from the 'Editions' menu. You must first, however, load the application 'SocketCommunicationsInterface' (and its prerequisites) - these are part of VAST.

If you are using the Parts interface to Socket Set you will need to copy the directory 'tobsock' (which contains icons) into your root VAST directory.

General Classes

• host := TobSocketsHost hostName: 'www.totallyobjects.com'.
• host := TobSocketsHost dottedDecimal: '209.140.118.187'.
• host := TobSocketsHost hostNameOrDottedDecimal: aString. "If aString could be a host name or a dotted-decimal string"
• host := TobSocketsHost byteArray: #[209 140 118 187].
• host := TobSocketsHost localHost. "If the host is the local machine"
• host := TobSocketsHost any. "Any local host"
• host := TobSocketsHost loopback."Use the loopback value 127.0.0.1"

You then need to specify the address (comprising a host and port number) you wish to connect to. You use the TobSocketsAddress class to do this. For example:

address := TobSocketsAddress host: host portNumber: 21.

The client side to the TCP/IP protocols in the Socket Set are subclasses of TobSocketsProtocol. These subclasses can be instantiated using #new or #statusStream: (which requires a WriteStream as input to which status messages would be put).

Sending Mail Using SMTP

To specify the recipients (or recipients of copies) use these methods:

Method	Description
addRecipient:	Adds a recipient (a TobSocketsMailRecipient)
addRecipient:emailAddress:	Adds a recipient using name and email address (both Strings)
addCopyRecipient:	Adds a recipient of a copy (a TobSocketsMailRecipient)
addCopyRecipient:emailAddress:	Adds a recipient of a copy using name and email address (both Strings)
addBlindCopyRecipient:	Adds a recipient of a blind copy (a TobSocketsMailRecipient).
addBlindCopyRecipient:emailAddress:	Adds a recipient of a blind copy using name and email address (both Strings)

To send the message use TobSocketsSMTP>>#mail:address: giving the message and the address as arguments.

For example:

(TobSocketsSMTP statusStream: Transcript)

mail: (

TobSocketsSMTPMailMessage new

sendersEmailAddress: 'matt@myserver.com';
sendersName: 'Matt Sims';
subject: 'Message from Totally Objects';
messageText: 'This was sent using the Socket Set!';
addRecipient: 'Joe' emailAddress: 'joe@bloggs.com';
addRecipient: 'Fred' emailAddress: 'fred@smith.co.uk';
addCopyRecipient: 'My Boss' emailAddress: 'boss@here.com')

address: (

TobSocketsAddress

host: (TobSocketsHost hostName: 'mail.mymailserver.com')
portNumber: 25)

To send any items in the header of the message (in addition to those automatically created) use TobSocketsSMTPMailMessage>>#extraHeaderItems: and give it a Dictionary where the keys are the header item names (e.g. 'DigitalCertificate:') and the values are the header item values.

To find out how successful the sending was (assuming no error occurs) you can send the resulting TobSocketsSMTP object the message #statusOfRecipients. This will answer a Dictionary with the recipients (or recipients of copies) as keys and TobSocketsSMTPRecipientStatus objects as values.

To add attachments use these methods (in TobSocketsSMTPMailMessage):

TobSocketsSMTPAttachments have four basic attributes: The contents, the encoding to be used, the type and the subtype. The Internet Request For Comments 1341 should be consulted for a definitive explanation of the acceptable values. The following methods should be used to set these attributes:

Method	Description
type:	Requires a String. Valid values are 'application', 'audio', 'image', 'message', 'multipart', 'text', 'video' or any String prefixed with 'x-'.
subType:	Requires a String. Valid values depend on the 'type' specified.
applicationType:	Sets the type to 'application' and the subType to the argument provided.
audioType:	Sets the type to 'audio' and the subType to the argument provided.
imageType:	Sets the type to 'image' and the subType to the argument provided.
messageType	Sets the type to 'message' and the subType to 'rfc822' (the only valid subType for thetype).
multipartType	Sets the type to 'multipart' and the subType to 'mixed'.
textType:	Sets the type to 'text' and the subType to the argument provided ('plain' or 'richtext').
videoType:	Sets the type to 'video' and the subType to the argument provided.
content:encoding:	Sets the content of the attachment (a String). The second argument specifies which encoding has been applied to the content (not the encoding to be applied). Valid encodings are 'BASE64', 'QUOTED-PRINTABLE', '8BIT', '7BIT', 'BINARY' or a String prepended with 'X-'. For ASCII text '7BIT' should be used.
base64EncodeContent:	Sets the content of the attachment (a String) and specifies that base64 encoding should be applied. This is ideal for sending binaries.
quotedPrintableEncodeContent:	Sets the content of the attachment (a String) and specifies that Quoted-Printable encoding should be applied. This is ideal for formatted text.
rawContent:	Sets the content of the attachment (a String) and specifies that it should not be encoded. This is ideal for 7-bit ASCII.

The following code snippet shows how you might send a binary executable and some binary application data as attachments.

| fs |

fs := CfsReadFileStream open: 'c:\myapplicationfile'.

TobSocketsSMTPMailMessage new

messageText: 'See attachments.';
subject: 'Message to Customer';
addRecipient: 'Customer' emailAddress: 'customer@foo.com';
sendersName: 'Me';
sendersEmailAddress: 'me@bar.com';
addAttachment: (

TobSocketsSMTPAttachment new

textType: 'plain; name="binary.exe"';
base64EncodeContent: '..binary data here..'; yourself);

attachApplicationDataStream: fs name: 'myappfile' applicationName: 'X-myapp';
mail: (

TobSocketsAddress

host: (TobSocketsHost hostName: 'mail.server.com')
portNumber: 25).

fs close

Notice that the above code uses an alternative way to send email (by creating the message and using the method #mail:).

Downloading Mail Using POP3

To use the POP3 protocol to access a mailbox an instance of TobSocketsPOP3 should be created and then configured using the methods:

#address: "which identifies the address of the server"
#username: "set the username of the mail account"
#password:

#deleteAllMessages
#numberOfMessages "Answers the number of messages in the mailbox"
#remoteMessagesDo: "Iterates over the messages"
#retrieveAllMessages
#retrieveAndDeleteAllMessages

So to download all messages from the server and delete them (so they are not downloaded again next time) the code would look something like this:

(TobSocketsPOP3 statusStream: Transcript)

address: (TobSocketsAddress

host: (TobSocketsHost hostName: 'mail.mypopserver.net')
portNumber: 110);

username: 'matt';
password: 'mypassword';
retrieveAndDeleteAllMessages

The answer to the above message will be an OrderedCollection of objects of the class TobSocketsPOP3MailMessage. These objects understand the following methods:

An incoming mail with attachments will answer an OrderedCollection of TobSocketsPOP3Attachments when sent the message #attachments. These objects understand the following methods:

Uploading And Downloading Files Using FTP

The method TobSocketsFTP>>#downloadFile:address:username:password:account:type:stream: has been provided for downloading files. It can be used as follows:

| fileStream |

fileStream := CfsReadWriteFileStream openEmpty: 'c:\thefile.txt'.

(TobSocketsFTP statusStream: Transcript)

downloadFile: '/export/datafiles/thefile.txt'  "The path of the file on the server"
address: (

TobSocketsAddress

host: (TobSocketsHost hostName: 'myserver.co.uk')
portNumber: 21)

username: 'matt'
password: 'mypassword'
account: ' "Account information is usually an empty string"
type: 'A'  "'A' for ASCII files or 'I' for binary files"
stream: fileStream.  "Where to put the downloaded file"


fileStream close.

Similarly the method TobSocketsFTP>>#uploadFile:address:username:password:account:type:stream: has been provided for uploading files to servers. Two additional uploading methods can also be used. TobSocketsFTP>>#uploadAppendFile:address:username:password:account:type:stream: appends the contents of the stream onto the file on the server (or creates a new file if one does not already exist). TobSocketsFTP>>#uploadUniqueFile:address:username:password:account:type:stream: will use a different file name (chosen by the server) if the file already exists on the server.

Deleting or renaming files can be done with TobSocketsFTP>>#deleteFile:address:username:password:account: and TobSocketsFTP>>#renameFile:to:address:username:password:account:. For example:

(TobSocketsFTP statusStream: Transcript)

renameFile: '/export/datafiles/small.txt'
to: 'big.txt'
address: (

TobSocketsAddress

host: (TobSocketsHost hostName: 'myserver.co.uk')
portNumber: 21)

username: 'matt'
password: 'mypassword'
account: ''.

To handle stalling during data transfer you can set the #stallTimeOut value of the TobSocketsFTP object. Whenever there is inactivity for a period either ExTobSocketsReceiveTimedOut or ExTobSocketsSendTimedOut will be signalled.

The default value is got from the class method defaultStallTimeOut which is initially 0 (i.e. ignore time-outs).

You can also download files using FTP by creating a URL. To create the URL object you can do either:

TobSocketsURL from: 'ftp://myserver.co.uk/export/datafiles/small.txt'.

Or,

'ftp://myserver.co.uk/export/datafiles/small.txt' tobSocketsAsURL.

The resulting object (an instance of TobSocketsFTPURL) can be sent any of the following messages to download a file:

#stream:
#stream:emailAddress:
#stream:emailAddress:statusStream:
#stream:statusStream:

ftp://<user>:<password>@<host>:<port>/<url-path>

So to download the file given in the earlier example:

| fs |
'ftp://matt:mypassword@myserver.co.uk@21/export/datafiles/small.txt' tobSocketsAsURL

stream: (fs := CfsWriteFileStream openEmpty: 'c:\thefile.txt')
statusStream: Transcript.

fs close.

TCP/IP Clients

If you wish to use the Socket Set to implement the client end of your TCP/IP protocols then you have two options:

(1) Subclass TobSocketsProtocol and follow the style of the existing subclasses (TobSocketsSMTP is a good example).
(2) Open and close sockets directly.

An example of option (2) is given below.

Say you have a TCP server (listening on port 9000) that will reverse the order of strings that you send it and responds with appropriate messages upon success or failure. The code might look something like this:

| s replyStream |

"Make a socket"
s := TobSocketsSocket newStream. "#newStream for TCP #newDatagram for UDP"

"Connect it to your server on port 9000"
s connect: (

TobSocketsAddress

host: (TobSocketsHost hostName: 'myserver.co.uk')
portNumber: 9000).


"Check the server gives the appropriate greeting on connection"
(s nextLine = 'String reversing server ready.') ifFalse: [self error: 'Bad reply'].

"Send a request to reverse a string"
s nextPutAll: 'REVERSE Mary had a little lamb'; cr.

"Stream over the reply"
replyStream := ReadStream on: (s nextLine).

"Does the reply start with 'OK'?"
(replyStream upTo: $ ) = 'OK' ifFalse: [self error: 'Could not reverse'].

"Close the socket because we are done"
s closeSocket.

"The rest of the stream contents is the reversed string"
^ replyStream upToEnd

Methods in the TobSocketsSocket class that are of general use:

Time-outs: Notice that there are four types of time-out:

connectTimeOut - this specifies how long to wait for a connection to a port
receiveTimeOut - this specifies how long to wait when receiving bulk data from the socket (using the #peek:, #next: and similar methods)
sendTimeOut - this specifies how long to wait when sending data on the socket
upToTimeOut - this specifies how long to wait when receiving from the socket one byte (or character) at a time (using #upToAll: and similar methods)

TCP/IP Servers

Creating TCP/IP servers can be a more complicated than clients, so the Socket Set provides you with the utility class TobSocketsServer (and its subclasses TobSocketsDatagramServer and TobSocketsStreamServer) to do the work for you.

To create a server you simply use the class method #address:clientBlock:.

The first argument is the address that you want to listen on and the second is a single argument block where the argument is the socket to a client that connects.

This example creates server corresponding to the client example above.

| server |

server := TobSocketsStreamServer

address: (TobSocketsAddress

host: (TobSocketsHost localHost)  "Listen on local machine"
portNumber: 9000)

clientBlock: [:cs |

| requestStream |

"Send greeting after a client connects"
cs nextPutAll: 'String reversing server ready.'; cr.

"Receive a request from the client"
requestStream := ReadStream on: (cs nextLine).

"This server can do only REVERSE"
(requestStream upTo: $ ) = 'REVERSE'

ifFalse: [cs nextPutAll: 'BAD REQUEST'; cr]
ifTrue: [

"Send the reversed string"
cs nextPutAll:('OK ' , (requestStream upToEnd reverse)); cr].


"Don't need to close the client socket because this is done automatically"

].


"Assign the server to a global so that we can access it later to stop it"
TobSocketsServer testServer: server.

"Start the server in the background"
server forkAt: (Processor userBackgroundPriority).

To try out the above code execute it, open a terminal application (Select 'Run...' from the 'Start' menu and type 'telnet' to get the application that comes with Windows 95 or NT). Connect to your machine on port 9000. You should see the prompt 'OK'. Next type 'REVERSE some text' (you may not be able to see what you are typing) and press 'Enter'. Then you should then see 'BAD REQUEST' (if you made a typo) or 'OK txet emos'. The connection will then be closed.

To stop the server execute:

TobSocketsServer testServer stop

Alternatively, the server will automatically be stopped if the process in which it runs is terminated using the debugger. Note that the name of the process includes the address and port number for easy identification.

Most of the time you will find that this simple approach to servers does everything you need, but there are a few more methods that you may find useful:

Note About Process Management

Your servers will usually need to manage many simultaneous connections from clients. If this is the case the server should be configured to fork child connections (the default setting); that is, create a new process for each connection. The server object will automatically manage the resumption of these child processes to simulate asynchronous behaviour. If, however, you do not wish the server object to automatically resume the child process (say, to delay or wait on a semaphore) then the message #resumedByServer: can be sent to the process with argument false. Alternatively the method #notResumedByServerDuring: can be used. For example:

server := TobSocketsStreamServer

address: (TobSocketsAddress

host: (TobSocketsHost localHost)
portNumber: 9000)

clientBlock: [:cs |

"..."
Processor activeProcess notResumedByServerDuring: [

(Delay forSeconds: 10) wait
]
"..."

].

UDP Clients

If you wish to use UDP instead of TCP (to send datagrams to a server) then the process is simpler. You first create the socket using #newDatagram, create a new TobSocketsDatagram and then send it using the #sendDatagram:to: message. For example:

| s |
s := TobSocketsSocket newDatagram.
s

sendDatagram: (

TobSocketsDatagram data: 'This is the contents of the datagram')

to: (

TobSocketsAddress

host: (TobSocketsHost hostName: 'myserver.co.uk')
portNumber: 9000)

UDP Servers

Creating a UDP server is very similar to creating a TCP server. The main difference being that the argument to the client block is the incoming datagram. For example:

| server |

server := TobSocketsDatagramServer

address: (TobSocketsAddress

host: (TobSocketsHost localHost)  "Listen on local machine"
portNumber: 9000)

clientBlock: [:datagram |

datagram inspect].


"Assign the server to a global so that we can access it later to stop it"
TobSocketsServer testServer: server.

"Start the server in the background"
server forkAt: (Processor userBackgroundPriority).

To specify the maximum size of the data of incoming datagrams send the server the message #bufferSize:. Any data larger than this value will be truncated and the 'truncated' flag set to true. The message #timeOut can be sent to the server. This specifies the period of the time the server should be prepared to wait when no datagrams are being sent to it. If the period is exceeded then an ExTobSocketsReceiveTimedOut exception is signalled. Setting the value to 0 (the default value) means that the server will not time out.

The incoming datagram understands three special messages:

To stop the example server execute:

TobSocketsServer testServer stop

Alternatively, the server will automatically be stopped if the process in which it runs is terminated using the debugger. Note that the name of the process includes the address and port number for easy identification.

Socket Set Exceptions

A description of each is given below. Indentation denotes the parent-child relationships between exceptions.

ExError
ExTobSockets  - An abstract exception (i.e. it is never signalled itself).

ExTobSocketsSocket  - This is signalled when a low level socket operation causes an error. This can be signalled when accepting, receiving, sending, connecting, binding, listening or closing. This exception is signalled with a single argument which is an instance of SciError.
ExTobSocketsConnectAborted  - This is signalled when TobSocketsSocket>>#connect: causes the connectLoopBlock to return 'false'.
ExTobSocketsClosed  - This is signalled whenever there is an attempt to sent or receive data on a closed socket. This exception is signalled with a single argument: the TobSocketsSocket that caused the error.
ExTobSocketsHost  - This is signalled whenever a socket tries to connect or bind to an invalid host. (Note that a TobSocketsServer will try to bind after being sent the #start or #forkAt: message). This exception is signalled with a single argument: the TobSocketsHost that caused the error.
ExTobSocketsTimedOut  - An abstract exception

ExTobSocketsConnectTimedOut  - Signalled whenever a attempt to connect a socket times out. This exception is signalled with a single argument: the TobSocketsSocket that caused the error.
ExTobSocketsReceiveTimedOut  - Signalled whenever a attempt to receive from a socket times out. This exception is signalled with a single argument: the TobSocketsSocket that caused the error.
ExTobSocketsSendTimedOut  - Signalled whenever a attempt to send to a socket times out. This exception is signalled with two arguments: the first is the TobSocketsSocket that caused the error and the second is the data that was tried to be sent.
ExTobSocketsUpToTimedOut  - Signalled whenever a attempt to send to a socket times out. This exception is signalled with two arguments: the first is the TobSocketsSocket that caused the error and the second is the collection received so far during the failing message.

ExTobSocketsFTP  - An abstract exception. All child exceptions are signalled with a single argument which is an instance of the class TobSocketsFTPError. For further information about the cause of the error, send this object the message #errorCode. For a more detailed explaination as to the meaning of these codes consult RFC 959.

ExTobSocketsFTPConnect  - Signalled whenever an FTP server sends an error message after the client connects.
TobSocketsFTPDataChannel  - Signalled if there is a problem establishing a data channel to the server. Data channels are needed whenever a file is uploaded or downloaded, or whenever a directory listing is downloaded. This exception is signalled with a single argument which is an instance of the class TobSocketsFTPError.
ExTobSocketsFTPDelete  - Signalled whenever a server has a problem when deleting a file.
ExTobSocketsFTPLogin  - Signalled whenever there is a problem during login that is not handled by the child exceptions ExTobSocketsFTPAccount, ExTobSocketsFTPPassword or ExTobSocketsFTPUser.

ExTobSocketsFTPAccount  - Signalled if the account information (when used) is not accepted by the server during login.
ExTobSocketsFTPUser  - Signalled if the username is not accepted by the server during login.
ExTobSocketsFTPPassword  - Signalled if the password is not accepted by the server during login.

ExTobSocketsFTPQuit  - Signalled if the quit command (sent at the end of all public instance methods in the 'TobSockets-API' category of TobSocketsFTP) is rejected by the server.
ExTobSocketsFTPReceiving  - Signalled whenever there is a problem downloading on the data channel.
ExTobSocketsFTPRename  - Signalled whenever a server has a problem when renaming a file.
ExTobSocketsFTPSending  - Signalled whenever there is a problem uploading on the data channel.
ExTobSocketsFTPType  - Signalled whenever a server does not like the given type when uploading or downloading.

ExTobSocketsSMTP  - An abstract exception. All child exceptions are signalled with a single argument which is an instance of the class TobSocketsSMTPError. For further information about the cause of the error, send this object the message #errorCode. For a more detailed explaination as to the meaning of these codes consult RFC 821.

ExTobSocketsSMTPConnect  - Signalled whenever an SMTP server sends an error message after the client connects.
ExTobSocketsSMTPData  - Signalled if the server sends an error message as a result of the client sending the raw mail message. ExTobSocketsSMTPHello  - After connection, an SMTP client will always greet a server with a 'HELO' message. This exception is signalled whenever a server has a problem with this greeting.
ExTobSocketsSMTPMailSend  - Signalled if the server sends an error message after the request to send mail.
ExTobSocketsSMTPQuit  - Signalled if the quit command (sent at the end of all public instance methods in the 'TobSockets-API' category of TobSocketsSMTP) is rejected by the server.
ExTobSocketsSMTPRecipient  - Signalled if the server does not like information about a recipient when sending mail. This does not neccessarily mean that the recipient does not exist.

ExTobSocketsPOP3  - An abstract exception. All child exceptions are signalled with a single argument which is an instance of the class TobSocketsPOP3Error. For further information about the cause of the error, send this object the message #errorObject.

ExTobSocketsPOP3Connect  - Signalled whenever a POP3 server sends an error message after the client connects.
ExTobSocketsPOP3Delete  - Signalled whenever there is a problem deleting a message on the server.
ExTobSocketsPOP3Login  - An abstract exception. Children are signalled if there is a failure during login.

ExTobSocketsPOP3Password  - Signalled is the password is not accepted by the server.
ExTobSocketsPOP3User  - Signalled is the username is not accepted by the server.

ExTobSocketsPOP3Quit  - Signalled if the quit command (sent at the end of all public instance methods in the 'TobSockets-API' category of TobSocketsPOP3) is rejected by the server.
ExTobSocketsPOP3Retrieve  - Signalled if a problem occurs during message download.
ExTobSocketsPOP3Stat  - Signalled if the server has problems establishing the state of the messages it has.

ExTobSocketsURL  - An abstract exception. Children are signalled if a String is being used to create a TobSocketsURL (or one of its subclasses) but contains some error. The first argument in all children is the String being used.

ExTobSocketsBadURL  - Signalled when the URL is invalid. The second argument is a description of the problem.
ExTobSocketsUnsupportedURLProtocol  - Signalled when the URL identifies a protocol not supported by Socket Set (or the appropriate class has been removed from the image). The second argument is the name of the attempted protocol.

Using Socket Set's Parts

A new parts category ('Totally Objects' Socket Set') will be added to the Composition Editor. This category contains ten parts. These are:

• Host
• Socket Address
• SMTP Socket Address
• POP3 Socket Address
• FTP Socket Address
• SMTP Mail Message
• POP3 Mail Message
• SMTP Mail Attachment
• POP3 Mail Attachment
• Mail Recipient

To see examples of these parts in action load the configuration map 'Totally Objects, Socket Set - Parts Examples'. A brief overview of each is given below.

TobSocketsPartsExamplesFTPClient

Host Name:  ftp.microsoft.com
Port Number:  21
Username:  anonymous
Password:  your@email.address
Path:  /dirmap.txt

Then press 'Download...' and enter the name of the file you would like to create locally.

After a short while the file should be downloaded.

TobSocketsPartsExamplesSMTPMailSender

Recipient's name:  Joe Bloggs
Recipient's email address:  joe.bloggs@widgets.com
Subject:  Testing the Parts
Sender's name:  Your Name
Sender's email address:  your@email.address
SMTP server:  mail.myserver.com
SMTP port number:  25
Message:  This is a test message

Similarly TobSocketsPartsExamplesSMTPMailWithAttachment can be used to send internet mail with a simple text attachment.

TobSocketsPartsExamplesPOP3MailReader

Username:  myusername
Password:  mypassword
POP3 host:  mail.myserver.com
POP3 port number:  110

Further Information

If you would like to ask any questions about this product, its operation or its commercial terms, please contact sales@totallyobjects.com.

Copyright (c) 2002 DirectDual Limited (trading as TotallyObjects).

Totally Objects - DirectDual Limited,
34 Compton Avenue,
Gidea Park, Essex,
RM2 6ES, England.
Tel: +44 1708 733295
Fax: +44 1708 783438
sales@totallyobjects.com
DirectDual Limited is an IBM Object Connection member.