Using AMarquee

Introduction on how AMarquee is working

The AMarquee library allows you to do network broadcasting in an asynchronous, multithreaded manner, with almost no knowledge of TCP programming. It does this by creating a background process that handles the TCP transmission and reception for you, and sends you events (called QMessages) to notify you of data you have recieved. Each of the *Op() functions in QSession class creates a message with your data in it, and sends it to the TCP thread for queueing and eventual transmission. With this setup, your code need never wait while data is transmitted or recieved, unless it wants to.

It is important to understand how data is accessed in the AMarquee system. All AMarquee public data is stored in a tree on the server, and each node in the tree has a name, which is a null-terminated string. Each node may be referenced via a "regular node path string", which is somewhat like a UNIX file path. Each client program that connects to the AMarquee server is automatically given its own "directory" node in the tree, based on the IP name of the computer it is running on, and the name it has chosen for itself. Thus, if you are running an AMarquee-based client program on a computer named mycomputer.mycompany.com, and it connects to the server as "MyProgram", then the program's "home directory" would be

/mycomputer.mycompany.com/MyProgram

And if you were to add a node named "MyData" to your "directory", it would show up as

/mycomputer.mycompany.com/MyProgram/MyData

All nodes in the server's data tree may be accessed or referred to by strings such as these. Also, each node in the data tree contains a data buffer of variable size. (So much for the filesystem analogy-- nodes in this tree can be both "files" and "directories" at once!) This data buffer is a simple, raw array of bytes, and hence may contain any data you wish to keep in it. The data buffer of the "home directory" node is hard-coded to a null-terminated string containing the IP number of your host computer, but the data buffers of all other nodes may be set arbitrarily.

Also: There is a "short" method of specifying nodes that are located within your own directory space. If you specify a path string without an initial slash, it will be assumed you mean the path is relative to your home node. Thus, specifying "MyData/DataItem1" as a node path would be the same (for most purposes) as specifying

/mycomputer.mycompany.com/MyProgram/MyData/DataItem1

Lastly, AMarquee makes heavy use of the Amiga wildcarding system to specify groups of nodes. Thus, to specify all client programs running on all connected computers, you could use

/#?/#?

Or to specify all entries under the node "MyData", that begin with the string "DataItem", from computers in Australia, that are connected via an AMarquee client registered as MyProgram, you could do:

/#?.au/MyProgram/MyData/DataItem#?

All matching and storage of nodes is case sensitive!!

Probably the best way to get a feel for how AMarquee works is to look at and play around with the example programs in the example directory of this distribution.

How to interpret QMessages (AMarqueeEvents)

Privileges/permissions

The AMarquee package API (JavaDoc)

(c)Håkan Parting 1998. Last update 16th June 1998