2 Files which is distributed along with this agent
3 Installation
3.1 How to install the UNIX-based part of NetAgent
3.2 Initalizing the NetAgent on the Macintosh
4 Talk 4
4.1 Pick talk...
4.2 Launch talk
5 Mail
5.1 On/Off
5.2 Read mail
5.3 List account
5.4 New account
5.5 Delete account
5.6 Mail configure
6 News
6.1 News on the Macintosh (NetAgent)
6.2 On/Off
6.3 Read...
6.3.1 The news-window
6.3.2 Delete-button
6.3.3 Mark read-button
6.3.4 Mark unread-button
6.3.6 Textfield
6.3.7 The article-window
6.3.8 Save as-button
6.4 Retrieve
6.5 News configure
6.6 News timestep
6.7 Subjects...
6.7.1 Subjects-window
6.7.2 List field
6.7.3 Editable textfield
6.7.4 Add button
6.7.5 Replace button
6.7.6 Delete button
6.7.7 Select all button
6.7.8 Options
6.7.9 Options-window
6.7.10 Send button
6.8 User/servers...
6.8.1 User/server window
6.9 News on Unix
6.10 How to start agentd and agentc
7 "Who is on"
7.1 On/Off
7.2 Icons
7.3 "Who is on list"
7.4 "Who is on Configure"
8 Sources
1 Preface
This is an unsupported product. It was developed as part of a study at Ostfold Regional College, Norway in the spring of 1992.
You use this software at your own risk. Neither the authors nor the Ostfold Regional College nor any other person or organization except yourself is responsible for any damage or loss of data derived from the use of this software. You may distribute this software freely as long as it is in its original form and all of its files are included. If you make any changes to any part of this software or the files distributed with it, please state so and do NOT distribute it under its original name.
We hope that you will find this agent useful and that it will act as an inspiration to other agents in the future.
The Authors:
Nina Beate Olsen
Morten Kristiansen
Per Henrik Johansen
2 Files which is distributed along with this agent
NetAgent - The NetAgent application. Used on an Apple Macintosh.
agentc.c - c file used to build the agentc application. Used on an UNIX-machine.
agentd.c - c file used to build the agentd application. Used on an UNIX-machine.
div_func.c - Some c functions which is used by the agentc and agentd programs.
div_func.h - Definitions for the functions in div_func.c.
filelock.c - Filelock functions used by the agentc and agentd programs.
filelock.h - Definitions for the functions in filelock.c.
nntp_tcp.c - Communication routines used by the agentc and agentd programs.
nntp_tcp.h - Definitions for the functions in nntp_tcp.c.
server.c - Routines used by the agentd program.
server.h - Definitions for the functions in server.c.
subjects.c - Routines used by the agentc program.
subjects.h - Definitions for the functions in subjects.c.
userdoc - This document.
3 Installation
The NetAgent is separated into two parts, one is running on an Apple Macintosh and one designed to run on an UNIX-host. Below we will discuss how to install the UNIX-part and how to set some of the variables used in the Macintosh-part of the NetAgent.
3.1 How to install the UNIX-based part of NetAgent
Put all the files except for the NetAgent application and this document on the UNIX host. Then type 'make'. You should now have produced two files: agentc and agentd (and several files named *.o, but ignore these). These two files are two runable files(programs). Their purpose is to pick out news for the agent and to send them to the Macintosh agent. To run the agentd program type 'agentd port', where port is the port number on which this program should listen. Similar to run the agentc program type 'agentc host polltime', where host is the name of a NNTP host and polltime is the number of seconds between each poll the agentc program makes to the NNTP server. The NNTP-server must support the XHDR-command. These two programs should be run as background processes.
These two programs is designed to handle several users, so that each user don't have to run these program and occupy valuable CPU time, although it is possible. They will also make several other files and directories when users registrates themselves on a host. The following files will be generated for each user:
<user>.subjects - contains the subjects the user wants to check for.
<user>.newnews - indicates whether the user have new news or not.
<user>.articles - contains the articles which have been picked out to the user.
These files will be in a directory named <user>. <user> is the username for a user on this agent.
The following files are used by the agent to manage the users and the news:
agent.users - contains the name and password of all the users. NB: the passwords are not crypted.
New.News - new news since last poll.
3.2 Initalizing the NetAgent on the Macintosh
Before you send the agent out on missions you should set some 'variables' within the program, or else it may not work properly. You may want to read the the rest of this document before you do this, but you do not have to.
Select the 'News configure'-option from the 'News' menu. Then select the 'User/servers' submenu. Fill out all of the fields in the window this selection bring forth. If you have any questions about these fields, please read the chapter on the User/server-window later in this document.
4 Talk
The talk is not a part of the agent itself. You must obtain your own talk program to use this feature. The only thing NetAgent does is to launch your favourite talk application. The menu contains two items (fig.4.1). See your talk-applications documents for information on how to use it.
4.1 Pick talk...
Opens up a fileselector-box (fig.4.2) which you use to pick the talk program you want the NetAgent to launch. It does not have to be a talk program. You may use this menu to launch any application you want to.
4.2 Launch talk
Launches the talk application you chose in ╟Pick talk...╚.
5 Mail
The purpose of the mailpart of the agent is to check if there is any new unix-mail on those accounts that are registered. The mailpart is run in intervals chosen in the configure menu. At each interval the agent runs thru all accounts in the list. If there are any new mail, you will be told in the diagnostic message window. On startup and when you delete all or the last account, so that there are no accounts left, the menus on, list account and delete account will be shaded. The read mail menu will be shaded as long as you haven't got any new mail. When the mailpart is active, you will see a mark in front of the Mail menu, otherwise the menu name is Mail. Below are a description of every submenu of the Mail menu of the agent.
5.1 On/Off
This submenu turns the mailpart on and off. If the name of the menu is "Mail" (fig. 5.1) then the submenu should be "On". When selecting this submenu the name of the submenu is changed to "Off" and the name of the menu is changed to "ÑMail" (fig. 5.2). At this time the mailpart is active. When selecting this submenu again, the mailpart is set passive and the names are changed back again. If the news- and the "Who is on" part is turned off when turning on the mailpart, the diagnostic window is automatically shown. When closing the mailpart and the news- and fingerpart is turned off, the diagnostic window is also closed. You can turn off all parts of the agent by closing the diagnostic window.
5.2 Read mail
This submenu (fig. 5.3) is shaded as long as you haven't got any new mail since startup on the agent. When you got new mail on any account, that account will appear as a new submenu of Read mail. Then when you select this account, you will open the window showing all the subjects of unread and new mail on that account (fig. 5.4). Even if you turn off the mailpart, you will be able to select this submenu.
5.3 List account
This submenu (fig. 5.5) is shaded as long as you haven't registered any new account. Then when you have registered new accounts, they will appear as submenus of List account. This submenu will be available even if you turn off the mailpart of the agent. The purpose is to show all accounts that will be checked for mail.
5.4 New account
The purpose of this submenu (fig. 5.6) is to register new accounts. When selecting this submenu, you will open the window for registering a new account. In the Host field, you type any host as an IP-address, i.e. fenris.dhhalden.no. In the User field, you type any username on the registered host, i.e. mortenb. And in the Password field, you type the password for that user on that host. When clicking on the password field, the blinking cursor will disappear, but you can still typing the password. The password will not appear in the password field, instead a Ñ will appear for every letter in the password. When an account is registered, the window will be closed.
5.5 Delete account
This submenu (fig. 5.7) has two functions. One is to delete all accounts, by selecting the submenu All. And the other is to delete one particular account, by selecting the submenu that has the name of that particular account. If you delete all accounts or you delete the one and only account, the submenus List account and Delete account will be shaded until you register a new account.
5.6 Mail configure
The configure menu has two submenues. The first submenu is Mail timestep (fig. 5.8), which decides how often the mailpart will be triggered. The numbers are in minutes. If the time to proceed one check of all accounts extends the time for a new trigger, the next trigger will be set from the time the that checking is finished. This is to prevent looping. On startup timestep will be set to the last setting when using the agent.
The second submenu Sorting keywords (fig. 5.9), used to sort the mail presented under the submenu Read mail. Here you have the opportunity to add a new keyword, delete a keyword, replace/editing a keyword or to insert a new keyword (fig 5.10).
To add a new keyword, you type the new keyword into the field New keyword and then click at the button Add. Then the keyword will appear after the last line of the field Sorting keywords.
To replace/edit a keyword, you must click at the keyword you wish to change in field Sorting keywords. Then the word will appear in the field New keyword for editing, then when you click at the button Replace, the keyword will be changed.
To delete a keyword, you have to click at the keyword you want to delete and then click at the button Delete. You can also delete more than one keyword by holding the shiftkey down and then click at the words you want to delete and then click at the delete button. Or you can click at the button Select all and then the button Delete to delete all keywords in the field Sorting keywords.
To insert a new keyword, you have to click at the keyword in the Sorting keywords field you want the new keyword to be inserted before. Then type the new keyword in the field New keyword and then click at the button Insert.
6 News
The news-part of this agent is separated into two parts: the one used in the NetAgent program and the two programs running on an unix-machine. We will describe how to use the Macintosh-part first and then we will proceed with the two unix-programs. On how to install the programs see ╟Installation╚.
6.1 News on the Macintosh (NetAgent)
All of the uses of this part of the NetAgent can be accessible from the ╟News╚ menu (fig.6.1) in the menubar. We will go through all of the menu items for this menu and describe their functions and sub-functions. We will also explain all of the windows which will be opened on some of the menu selections.
6.2 On/Off
When you select this menu-item (fig.6.1) the first thing you will notice is that the "News" menu changes. A "Ñ" will appear before its name. This indicates that a background process which checks whether new news has arrived or not is running. If you take a look at the menu itself you will see that the "On"-selection you selected has become an "Off"-option (fig.6.2). If you select the "Off"-option, the "Ñ" before the "News"-menu will disappear and the "Off" will change to "On" again (the background process is no longer running).
The background process will report to the diagnostic window (fig.6.3) each time it is checking for new news (the diagnostic window is described earlier in this document).
6.3 Read...
You use this selection (fig.6.4) each time you want to read the news this agent has picked out for you. Probably the one you will use the most together with the Retrieve-selection (described later in this document). The news news╒ subjects will be presented to you in a window, called the news-window.
6.3.1 The news-window
This window (fig.6.5) presents the subjects of the news which the agent has picked out. The window contains a textfield (in which the subjects are listed) and four buttons (Delete, Mark read, Mark unread and Select all). We will discuss the buttons first and then the textfield.
6.3.2 Delete-button
When you press this button the selected subject(s) in the field (the highlighted lines) is erased.
6.3.3 Mark read-button
If you press this button a ╟├╚ is inserted before the selected subject(s). The ╟├╚ indicates that the subject(s) is considered read by the agent and will be deleted when closing the window. In addition to this the agent will NOT pick out new words to search for in future news-articles. It thinks that it has already picked words from this subject (for a more detailed explanation on this subject see the description of the text-field and the section in this document describing the subjects-submenu).
6.3.4 Mark unread-button
When pressed, the selected subject(s) in the text field is considered unread. If a ╟├╚ was inserted before the subject(s), it is removed. The agent WILL pick out new words if you read the subject(s) again (for a more detailed explanation on this subject see the description of the text-field and the section in this document describing the subjects-submenu).
6.3.5 Select all-button
When you press this button all of the subjects in the textfield is highlighted (selected).
6.3.6 Textfield
The textfield contains all subjects of the articles the NetAgent has picked out for you. If you want to read an article just double-click on the line which contains the subject you want to read. This will open up a new window (article-window), in which the article is displayed. If more than one line is selected in the field when you double-click on a subject, no article will be displayed. Thus, only one article can be displayed at any time.
When you double-click on a subject you will start up a process in the NetAgent. It will divide up the subject into words. These words will then, along with the subject itself, be added to the subject-list. The subject-list contains all the words you wish the agent to search for in future articles (see subjects-submenu for more on this). It will also update the word(s) the article was picked from. This option may be turned off if you don╒t want the agent to do this. See Subjects-Options
6.3.7 The article-window
This window (fig.6.6) contains a textfield, in which the article is displayed, and a button, Save as-button.
6.3.8 Save as-button
When you press this button you will be presented with a fileselector-box (fig.6.7), which you indicate where you will save the article displayed in the textfield in the article-window.
6.4 Retrieve
This selection (fig.6.8) is enabled when the agent has new news to show you (it also reports this in the status-window). Select ╟Retrieve╚ from the menu when you want to retrieve your new news. The subjects of these articles are then sorted into the textfield in the news-window. Select ╟Read╚ when you want to read your articles.
6.5 News configure
This menu-item (fig.6.9) contains three submenus: News timestep, Subjects... and User/servers... We will describe these in the above order.
6.6 News timestep
This submenu (fig.6.9) also contains another submenu in which you set the time between each time the NetAgent checks for new news. The numbers in the submenu is the time in minutes. The current timestep is the one with the ╟├╚ before its name.
6.7 Subjects...
Upon selection of this item (fig.6.10) a window will be opened, the subjects-window.
6.7.1 Subjects-window
This is the window (fig.6.11) where you may edit the list of words the NetAgent uses to pick out news for you. It contains a list field, a textfield and seven buttons. Both the listfield and the editable textfield are closely related, both with each other and to some of the buttons. We will describe each one of the elements separately, but we will give references to the other parts when needed.
6.7.2 List field
This field contains all the information the news-part of NetAgent needs to give you the articles you want. Each line in the field contains two sets of information. One is the word(s) the agent search the articles for, and the second is the priority of the word(s). The priority ranges from 1-9.
It also have an additional value of 0 which means that the word is disabled. The 0 priority will show as a ╟╞╚ in the field.
To change the priority of the word(s) just double-click on the line which contains them. You will then be asked to give the new priority of the word(s). You may also change several priorities by selecting multiple lines in the field.
If you select just one of the lines in this field (no double-click) you may edit this line in the editable textfield (Sorry, but not the priority).
The NetAgent also changes the priorities at run-time according to what articles you read, deletes and so on. So this field might not look the same the next time you see it after editing. There is a way to stop the agent from ╟messing╚ up this field. See Options-window later in this document.
6.7.3 Editable textfield
This field lets you edit the contents of one of the lines in the list field. You use this field together with the Add and Replace buttons to either: add the edited line as a knew line or to replace the selected line in the list field.
6.7.4 Add button
This button adds the contents of the editable text filed to the list field.
6.7.5 Replace button
This button replaces the contents of the selected line in the list field with the contents of the editable textfield. It doesn╒t work if multiple lines in the list field are selected.
6.7.6 Delete button
Deletes the selected lines in the list field.
6.7.7 Select all button
Selects all of the lines in the list field.
6.7.8 Options
When you press this button you will open a new window, the Options-window, where you set some options in the news-part of NetAgent.
6.7.9 Options-window
In this window (fig.6.12) you can set two options.
The first option you may set is whether or not the agent should ask for a priority when you add a new item to the subject-list or if it should use the default value.
The second is an option indicating if the agent should update and pick new subjects when you read a news article (or deletes one).
6.7.10 Send button
This button sends the words list to the agent running on an Unix-machine. Use this if you make changes to the list so that the agent can pick out the correct articles.
6.8 User/servers...
This selection (fig.6.13) lets you set some parameters/values the NetAgent application uses. You do this in the User/server window.
6.8.1 User/server window
This window (fig.6.14) contains 5 editable textfields. They are called User, Password, NNTP, Agent, Agentport. Below is a description of each of them.
User: This field contain your userid with the Unix-agent. If it is the first time you use the NetAgent, just give yourself a name.
Password: The password you want to use as your password on the Unix-agent.
NNTP: The adress of the NNTP-server you wish to use. NB: it must support the article and the XHDR-command.
Agent: The adress of the Unix-agent.
Agentport: The port which the Unix-agent listens.
6.9 News on Unix
This part of the agent is made up of two programs: agentd and agentc. These two files will in turn generate a set of files for each user which is registered with them.
6.10 How to start agentd and agentc
Agentd is the agent-deamon which the NetAgent on the Macintosh communicates. It takes one parameter: the portnumber on which it is to listen.
Syntax: agentd portnumber
Agentc is a NNTP-client which will pick out the news for the users. It takes 2 parameters: the adress of the NNTP-server and the time between each check in seconds.
Syntax: agentc adress time
7 "Who is on"
The "Who is on" watches persons that you have registered in the Reg_new-window. When you register a person in the Reg_new-window, you will get the name in a list of the "Who is on"-window. You can watch anyone in the world. You can edit and delete persons from the list. You don╒t get the persons planfile, but you can easily find out which persons that are logged on/off. The persons registered in the list, have a picture in the Icon-window, where you can find out which persons that are logged on/off. The picture changes to blend if the person is not logged on. If a person logges on, the picture of that person will appear bright (not blend).
Now we will study the "Who is on" menu, windows and the use of the "Who is on".
The "Who is on" does not work unless you register a person. When you start the "Who is on" for the first time, you have to open the Reg_new-window. The Reg_new-window will be explained later. Let's start with the menu.
7.1 On/Off
This submenu (fig.7.1) indicates that the "Who is on" part either is on or off. If the name is On, the "Who is on" part is passive, and you can activate the "Who is on". If you do that, the "Who is on" menu changes from "Who is on" to "ÑWho is on". This indicates that the "Who is on" part is active. The submenu changes from On to Off. You can stop the triggering by selecting Off in the menu. If you choose to have "Who is on" active, the diagnostic message window (fig.7.2) will stay open. In this window you can check if the persons you want to watch is logged on or not.
7.2 Icons
The Icon-window (fig.7.3) is opened. This window is the most important one. You can watch all persons whether they are logged on or off. The window is changing size depending on how many persons you have registered. The picture will be pasted into an empty field of the window, when registering a new person.
7.3 "Who is on list"
This submenu (fig.7.4) opens the "Who is on"-window (fig.7.5). Now you have the chance to either edit or delete persons from the list. You can click on a name in the list, and the name will appear in the text field under the list. If you want to edit the name, edit the name in the text field, and click on the Replace-button. The edited name will appear at the same place as the old name. You can delete a person by selecting that person in the field, and then click on the Delete-button. The name will disappear from the list, and the picture of the person will disappear from the Icon-window. If there are several persons connected to the same picture, the picture will not disappear from the Icon-window. When the last person connected to the picture is deleted, the picture will disappear from the Icon-window.
7.4 "Who is on Configure"
The "Who is on Configure" contains two submenues. The first submenu "Who is on timestep" (fig.7.6) tells you when the "Who is on" shall be triggered. You can choose different timesteps due to how often you want the "Who is on" to be triggered. The timestep is in minutes, so if you choose timestep 2, the "Who is on" will be triggered every 2 minutes. The timestep you choose will be default next time you start the "Who is on".
The next submenu is "New persons" (fig.7.7). The Reg_new-window will appear on the screen, and you can register new persons (fig.7.8).
You will get a message that tells you to paste a picture. Click OK and open scrapbook, where you already have a picture of the person you want to register. Copy the picture from scrapbook/clipboard, activate the Reg_new-window and click on the Paste-button. The picture will now be shown in the frame of the Reg_new-window. After pasting the picture, write the address to the person like this:
<username>@<IP-address>
Example: mortenb@fenris.dhhalden.no
It does not matter either if you use return or click on the Reg-button, the person will in both cases be registered.
Now you have the opportunity to either register another person, and go through the same procedure again, or you can click on the picture of the person in the Icon-window, and the Reg_more-window will appear (fig.7.9).
In the Reg_more-window you register accounts that will be connected to the same person /picture that you have clicked on in the Icon-window. This is what you do if you want to register a group of people, for example a project group. The picture in the Icon-window will tell you that at least one of the group members are logged on, if the picture is bright.
8 Sources
Filetransfer ideas from HyperFTP background scripts by Douglas Hornig, Cornell University 1990.
Filename, NewFileName by steve Maller, Andrew Gilmartin, Jon Pugh, Apple Computer & Brown University, 1987.
TCPNameToAddr, TCPSend, TCPRecvUpTo, TCPState, TCPRelease, TCPClose, TCPPassiveOpen by Harry Chesley, Apple Computer Inc, 1989
TCPGetAddr, FRPxfer, TCPSendUrgent, translete by Douglas Hornig, Cornell University 1990.
How to use MacTCP and how to communicate with the NNTP-server is taken from the HyperCard stack 'netnews reader 1.2.1'.
Request for Comments (RFC)
RFC 850 - Standard for Interchange of USENET Messages
