The Basics

If BeShare is installed in your system — either from a Haiku .hpkg or just from unpacking the zip — to start it you simply double-click its icon. To actually do anything you have to be connected to a BeShare (MUSCLE) server. There are several of these, but the default you will see in the Server: control at the top of the window is "beshare.TyComSystems.com"; this has been the default for years and hopefully will continue so. If you click on the Server: menu button you will see a list of alternatives that you can select to try. (If you know of a server not on the list that you want to connect to, simply type it into the Server: text field.)

Before you actually connect. you may want to change your User Name: to something that suits you. Otherwise you will be known to the world as 'binky'... (Names are not forced to be unique, but choose something distinctive to avoid confusion. Best to avoid spaces in the name; they won't break things — much — but may confuse people trying to chat with you!) You can also change it any time later in the session if you need to. Note that most of the gadgets in the top area have a similar form, you can use the menu button to select an existing choice, or type in a desired new one.

Every time you type a new string into one of those "menu-gadgets", the string gets added to the menu list, so that — especially with the Query: (below) — can get a bit long. You can remove an item from the list by holding down <Ctrl> as you select it.

Once you're satisfied with these details, select "Connect to..." from the File menu at the top to link yourself in. You can use the "Disconnect" item later to leave if you want to keep BeShare running for some reason. Otherwise, quitting Beshare has exactly the same effect. If you want to connect automatically when you start BeShare, check the "Login on Startup" item in the Settings menu.

When connected, you'll see a list of the other currently-connected users (but not yourself) in the pane at lower right. The first name or so in the list is likely to be a 'Bot' (see later) or an admin account, but actual users will have a Status such as "here" or "away" that may (!) indicate their actual status. You set your own Status via the controls at upper right.

The large pane at lower left is where all messages — from the System or other users — are displayed. A bunch of these will have appeared when you connected, giving the status and, again, showing the users that are connected. All messages, except private ones to other users, appear here.

The upper left quadrant is where file queries and transfers are handled, see the next section below. To its right is where transfer status will be displayed.

When you quit BeShare, your current server and username, along with all your other settings, are saved to disc, and will be restored when next started. The file used is by default "/home/config/settings/beshare_settings", but you can also put "beshare_settings" in the same folder as BeShare itself, and this will take preference over the config/settings one. This is useful if. for instance, you want to have BeShare instances habitually connected to more than one server. Use separate folders with separate copies of BeShare (copies, not links) and their own settings files. Keeping a master — but unused — "/home/config/settings/beshare_settings" is also helpful to restore local settings files to their basic state.

Querying and Downloading

You can search for files you might be interested in by typing a string that you expect to be in the filename into the Query: box. Start the search with Start Query or simply by hitting <Enter>. The search is not case-sensitive. You can use the usual "shell" wild-card characters '*' (any string) and '?' (any character) to make a "regular expression", but if you do that the expression must match the whole file name. E.g. entering "zip" will find all zip files (and any other files with "zip" anywhere in the name) but "z?p" won't. You need to use a complete expression such as "*z?p" to get what you expect.

To find only files that have been shared by a particular user, append "@" and the user name to the query, e.g. "*.zip@pete". The user name part of the string obeys the same rules as above regarding regular expressions. If you like, you can use the ID of a user (or with wildcards for a group of users) instead of the name.

Until you click Stop Query, your query is live. Any relevant new files shared by a user, or ones removed, will correspondingly change the displayed list.

Each file displayed will include an icon and other attributes. With v3.00 or later, the icon will be the individual icon of the original, if it has one, otherwise you will see the icon associated with that filetype. The attributes shown are selectable with the Attributes menu. (Not all attributes that may be on the original are available — only generally relevant ones.)

Once you have spotted a file that might be of interest, click to select it. This will enable one or two buttons below the list panel. If you are running v3.00 or later you should have an "Information" button on the left; otherwise there will just be a "Download Selected Files". Information will open a panel showing any descriptive text the sharer may have attached to the file. In any case, clicking Download... will start transferring to your machine. You should see the progress in the panel on the right. (For things that might go wrong, see the "Firewalls..." section below.)

The exact folder that will hold your downloaded files depends on the version of BeShare. In most versions around, the "downloads" folder is in the same folder as BeShare itself. However, if you have installed it via Haiku's "Package Management" system, that folder is read-only, so this isn't possible. Version 3.01 for PM puts the "downloads", and "shared" (below), folder in "/boot/home/BeShare/". In any case, wherever those folders actually are, you can always access them directly from the File menu "Open..." items.

You can select more than one file by holding down <Alt> (in v3.00 and after) or <Opt> ("Windows" key) while clicking on their entries. Select a contiguous range with <Shift>. If you're sure you want a particular file you can double-click on it for immediate download, or you can drag the display entry directly to the folder where you would actually like to have it.

A sharer may have arranged their files into subfolders. If so, you can see this in the Path attribute. If a file is in a subfolder, and you have "Retain File Paths" checked in Settings, a transfer of that file will create any necessary corresponding subfolders in your "downloads" (or other target) folder, and place the file there. If the option is not checked, the file gets placed directly in the target.

Sharing Your Files

To make files available for others to download, just place them in the appropriate "shared" folder. Again, if you are running from an .hpkg, this will be "/boot/home/BeShare/shared" or similar, otherwise it is simply "shared" in BeShare's own folder.

Usually the simplest and best way to get a file into 'shared' is just to use a link. If you prefer, you can move or copy the file there, but be aware that if you copy the file its size and attributes won't get distributed to other clients until you disconnect from and reconnect to the server. (This is due to a characteristic of the BeOS/Haiku Node Monitor, which sends notification immediately a file is created, not when it is fully built.)

If you want to share a whole directory tree of files, just link the top-level directory into ''shared" The Path attribute on a viewer's BeShare should show the sub-paths of all the files. (Caution: there seems to be a bug that the 'shared' folder itself should not be a link, or the path may not be passed.)

File Information

with the v3.00 release of BeShare, a sharer can add some informational text to the files being shared, which can be read by those querying the files. This is simply a string attribute "BeShare:Info" attached to the file. (In v3.00 and later, the Information button brings it up in a window, but other versions will show at least one line of it as an attribute in the list.)

You can attach the attribute directly with the 'addattr' shell command, e.g.:

addattr BeShare:Info "this is some information about this file" <filename>

This is tedious, though, so a small xicon script is included in the package that will add the attribute to files dropped on it. It opens a StyledEdit window for entering the text.

Chatting

You can say something to any other users currently connected by typing it in to the Chat: field at the bottom. Your words will appear in everyone's 'messages' pane, prefaced by your ID and username.

.To send someone a private message, prefix the text with "/msg <name> ", and only <name> will see it. A session ID will do instead of the name if you prefer. You can give several names separated by commas to send to all those named at once. At least you can do that if there are no spaces anywhere... Any space after commas or in names will confuse things. A single user name with spaces in it will be recognized correctly provided it is currently valid. You can also use wildcards to specify a group.

For an ongoing private chat with someone, you can open a separate private-chat window by using "/priv " instead of "/msg ". Or you can do the same with a right-button menu on the username in the Name pane. The other person will need to do the same for a continuing conversation.

Using "/me " or "/action " as the prefix sends a message prefixed by "Action:" and your name to everybody. Useful if you want to indicate a physical reaction to something!

There are number of other "/…" commands recognized. Type '/help" to see a list.

If you want to reference a file you are sharing in your chat, you can drag the file's entry in the 'shared' Tracker window into the Chat: text field. It will appear on your readers' screens highlighted in blue, and they can click on that to put it into their Query field. Alternatively you can type in "beshare:<string>" where <string> can be the file name or a wild-card expression.

You can type in a URL ("http://…") that will be highlighted on everybody's screens in the same way. Clicking on that opens a browser window on that site. The special "beshare://…" can be used to reference a particular server; when another user clicks that, it invokes a new BeShare there for them.

Bots

Most servers have an attendant "Bot" to handle an extended set of tasks. On the Tycom site that's "Atrus". The Bot will normally have an ID of 0 or 1.

One of their more useful functions is to catch you up on conversations that happened while you were offline. e.g. on TyCom, type "Atrus catsup" into the chat field to see recent messages. (If you don't want others to know you asked, use '/msg Atrus catsup". This applies to any Atrus command.)

You can also leave a message for someone who is not currently connected. To leave a message for e.g. pete, type "/msg Atrus message for pete " followed (on the same line) by the actual message. (With the "/msg" prefix, assuming you want it private.) When pete connects later, he will be told "Message for you, Sir!", and can retrieve it by entering "Atrus messages". (The message is always delivered privately.)

The Bot will be able to provide other information, depending on the Bot. Use the "help" Bot command (e.g. "Atrus help") to find out what it can do.

Firewalls, Routers, LANs, and all that...

Because BeShare depends, for transferring files, on certain IP ports being available, it can have problems with firewalls. As long as the client sharing the files is not firewalled, there will be no trouble, whether you are firewalled or not, but if you are firewalled you can only share to non-firewalled clients, and you must check the "I'm Firewalled" item in the Settings menu. (This is so the two clients can rearrange how they find the needed ports.) The chat function isn't affected by firewalls.

When BeShare was first written, it was probably a bit uncommon for a home user to be firewalled — they would be connected directly tp their DSL line or such, with no firewall. these days you're much more likely to have a home network, behind a router which by default acts as a firewall. However, it is not an impenetrable one. As long as you have one machine, with a particular local adrress, from which you want to share files, you can set the router up to know about the ports that need to be open.

The ports that BeShare expects to be available are in the range 7000..7050 (normally only the first few of these — say 7000..7005 or so). You will need to set up "Port Forwarding" to your BeShare machine for these in your router. This is done via the setup web-page on your router (check its manual). The BeShare box will need to have a static LAN IP address. If your LAN uses DHCP, you will also need to tell the router to always assign the same dynamic IP to that box, based on the MAC of its net card.