The BeShare Handbook

BeShare is a file-sharing and chat app for Haiku and (originally) BeOS. Because it's OS-specific, it preserves the attributes of transferred files, and when you have file names displayed from a query they are displayed with their appropriate icons.

This handbook aims to cover some of the things that are not so obvious from the docs that come in the package.
 

Index

• The Basics
• Querying and Downloading
• Sharing Your Files
• File Information
• Chatting
• Bots
• Firewalls, Routers, LANs, and all that...

More interesting Informations

• BeShare Connectivity Investigations
• About BeShare Version 3.00

 

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.

Before you actually connect. you may want to change your User Name (in the control to the right of 'Server') to something that suits you. Othertwise 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.

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.

back to Index

 

Querying and Downloading

You can search for files you might be interested in by typing a string that you expect to be in their name 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, 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. (Most likely none at the moment...) 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.)

If your BeShare is from a Haiku .hpkg, you should find the transferred files in "/boot/home/BeShare downloads". If you have unpacked it from a zip archive (old-style) they will be in "downloads" in the same folder as BeShare itself.

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

back to Index

 

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", otherwise it is simply "shared" in BeShare's own folder.

Rather than moving or copying the files, it is usually more convenient just to use a link. 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 attribute may not be shown.)

back to Index

 

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, 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:

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.

back to Index

 

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 ", and only 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.

back to Index

 

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. (Using 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.

back to Index

 

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). 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.

back to Index

 

BeShare Connectivity Investigation

Some of us seem to be having difficulty downloading files from others, and I've been doing some experiments to try to de-confuse things. This file will be an updated log of these.

My main net-connected machine is my old BeOS developer's machine (running R5-BONE). I'm using BeShare 3.00 for all this, but tests with v2.28 and v2.27 all seem to behave the same.

All my machines are on a LAN, but the router is set to pass through BeShare's port 7000 to my BeOS box.
I can connect to the net from my lHaiku laptop, but there is no 7000 pass-through to that, so it is essentially firewalled. (Everything is static IP -- no dynamic.)

I seem to be able to share files to anyone from the BeOS. And I can DL files onto my laptop. But I can't share files (at all, as far as I can tell ) externally from the laptop. (I also have muscled running on a raspberry Pi on the same LAN, and of course local downloading works fine.)

I get different results if I set "Firewalled" on the laptop or not. If not, I see (on the requesting machine) "Queued (Remote machine too busy)" and then a "...Sent:.." report.
Then it hangs.
If I set "Firewalled", I get the "Awaiting Callback" report I see with other failures.
(I never see any reports on the laptop at all.)

Chatting with Lelldorin earlier, when we were getting "Awaiting Callback" trying to DL from him, he passed on his IP address, and I tried using netcat to check port 7000, and didn't find it open -- even though he thought it was.

[ For reference, here's the netcat command I use:

where options 'z' means "test for port open", 'v' means report result, and 'w 3' is the timeout

]

However, I later had strange results checking my own port from a remote machine (a shell account I have on a machine across country). I have 80 and 7000 supposedly open to the world, but nc showed 80, not 7000!

I also have an external shell account on my own ISP, so I tried from that, and it shows both ports open as I would expect.

And I've had mail back from my ISP's support, and they do not block 7000

So I'm wondering if some routes do block 7000...

I had port 7000 passed through my router, but looking at the code, it is going to need other ports in the range 7000-7050.
I've now added the whole range to my pass-through, so next time let's see if that helps transfers...

Ahah! Yesterday, I couldn't download (wia tycom) from my laptop to BeOS because the laptop doesn't have router pass-through and so is firewalled. Now, if I set "I'm Firewalled" on it, DL to BeOS works! So I guess it's important to set the router for the whole range.

back to Index

 

About BeShare Version 3.00

Beshare 3.00 is a somewhat enhanced version of the venerable file-sharing and chat app, originally for BeOS, but equally good for Haiku.

Files on this site:

BeShare_3.00.zip -- user files and docs

BeShare_3.00_src.zip -- complete source files

BeShare_3.00_ABOUT.zip -- this text

The following is an expanded dissertation on my reasons for wanting to put together a slightly revised version.
With the demise of BeBits and HaikuWare, and with barriers still apparently in the way of a generally usable repositary, we seem to need a convenient way of distributing apps and stuff to Haiku users.
If people were aware of it and used it, BeShare could be a part of the solution.

Over the years I've seldom used it, because the web sites were much more convenient for locating what one wanted, but with them gone BeShare could become a useful community.

When I use it, though, I find I'm faced with a long list of files, with no idea of what most of them are!
It struck me that it would be nice if whoever posts the files could tag them with some sort of short description, so that a prospective downloader could have some idea of what he was getting.

This was the main impulse for doing some coding, but when I started looking at it, I realized that icon handling wasn't the greatest, either. Only icons that belong to MIME types already on the viewer's machine are shown. Any custom icon associated with the file itself is not displayed in the list. As most apps, at least, have their individual icons, this was a bit of a limitation.

So I've added code that handles both the above concerns. A provider can tag their files with a 'BeShare:Info' attribute string, and a viewer can bring up that information in a window. Any mini-icon or vector-icon in the attributes of a file will also be added to the information sent to the MUSCLE server, and will be shown in the viewer's list. This does mean that a bit more space is used up by such entries on the server, but I don't think this should be excessive.

I also found one ancient bug that may have been causing occasional confusion over the years. If a file being downloaded had an attribute that was a BMessage, the sending BeShare would either truncate the attributes or -- 1 in 12 times -- crash! (The crash was when the flattened message was an exact multiple of 12 bytes...) Guess what the first file I chose at random for testing (because it has a nice icon) had as an attribute...
(:-/) Ah, the sense of humour of the Gods of Code...
Now fixed, of course.

The base source I used for the revision was v2.28
-- with associated MUSCLE 3.20, slighty tweaked for Haiku compatibility also --, specifically because I needed for it to run under BeOS as well as Haiku. My machine that spends the most time connected to the net is still my trusty old Be Developer's machine, so BeShare has to run on that.
I see no advantage for BeShare in later MUSCLE versions -- it seems to be flawless on the older one. And it connects just fine to muscled 6.02 on my Raspberry Pi.

I bumped the version to "v3.00", not because of any startling advance (:-)), but because others have used 2,30 and 2.31 for Haiku-only versions [that apparently don't entirely work! (:-))], so any 2.nn numbering would likely conflict.

The sources are available, but packaged separately, because I needed to include the slightly updated MUSCLE sources as well, increasing the bulk considerably. They should be located anywhere the user package is.

I haven't internationalized the 'Information' button, because to do so I'd have to add a string to the set of *every* supported language, and I don't feel competent for that. I'm hoping that the English word is understandable to most.
Similarly, because I can't really update them, I've left all the alternative-language docs out. If anyone else wants to take all that on...

Adding the Information tag:

'BeShare:Info' is just a normal string attribute, so you can just use the 'addattr' command to tag a file, but this becomes cumbersome, especially if the text is more than one line. So I've included a little xicon script 'AddInfo' that will open a StyledEdit window to enter/edit the tag for any file you drag onto the script icon. At the moment the script uses command options that only exist in Haiku, so it won't work in BeOS -- and of course you need xicon installed. Perhaps a little app might be written for this job eventually.

back to Index