HowTo:Enabling Sharing with Gaim
From iFolder
| Table of contents |
Introduction
This HowTo will show you how to add p2p (Peer-to-Peer) functionality to the iFolder Client using Gaim (http://gaim.sourceforge.net).
The Gaim file sharing solution presented here consists of two parts:
- The Simias Gaim Domain Thread Service
- The iFolder Gaim Plugin
This code currently only works in Windows and Linux. We intend to eventually create a plugin for Adium (http://www.adiumx.com/) for Mac OS X, but we have not yet had the time. If you have experience there and can help, please let us know.
Prerequisites
You will need to install a stable version of iFolder. This is not covered here but you can find a stable build from the Download page.
I don't want to compile code, just tell me how to get it working!
Unfortunately, we currently do not have a process to automatically build these components on a regular basis. When we finally do, we will update this section of this HOWTO document with the location of the binaries. If we do post some hand-built binaries for iFolder Gaim p2p we will post links to it on the Download page.
Getting the Source Code
You can checkout the source directly from our CVS repository on the Novell Forge site. For information on using CVS with Forge, look here:
http://forge.novell.com/modules/xfmod/cvs/cvspage.php/ifolder/
You will want to check out the "gaim-ifolder" module. As an alternative to using CVS directly, you can also browse the CVS repository with a web browser and download a tarball of the source code.
Building and Installing the Simias Gaim Domain Thread Service
Building this portion of the Gaim Domain is fairly straighforward. You will need to know the prefix of where iFolder/Simias is currently installed, since the binaries generated here have to be installed to the same location.
Run the following commands to configure, build, and install the Simias Gaim Domain Thread Service (the prefix shown in these instructions is the one used in the RPMs we release for Novell Linux Desktop):
cd gaim-ifolder
./autogen.sh --prefix=/opt/novell/ifolder3
make
make install (you will likely need to "su root" before running this)
Next, you'll need to edit a configuration file to enable the thread service. The file you need to edit is $prefix/etc/simias-client-bootstrap.config. In this file, you're looking for the line:
<Service name="Gaim Workgroup Domain" assembly="Simias.Gaim.dll" enabled="False" type="Thread" class="Simias.Gaim.GaimService" />
The line needs to be changed to have "True" instead of "False" like this:
<Service name="Gaim Workgroup Domain" assembly="Simias.Gaim.dll" enabled="True" type="Thread" class="Simias.Gaim.GaimService" />
^^^^
This will only enable the Gaim Domain if you've never run iFolder before. This bootstrap file is copied to your Simias data directory and is named, "Simias.config". If you have already run iFolder, you'll also need to update your "Simias.config" file. It has the same format as shown above. It's located in a different location depending on your platform:
Linux:
~/.local/share/simias/Simias.config
Windows:
$HOME_DIR\Local Settings\Application Settings\simias\Simias.config
Building and Installing the iFolder Gaim Plugin
As of right now, we have not spent the time to figure out how to build the iFolder Gaim Plugin separately from Gaim itself. Instead, we've created a patch file to apply before building Gaim which builds the iFolder Gaim Plugin all in the same process.
Don't worry, we'll walk you through the process here, although, if you're having issues building Gaim, you'll need to resolve those on your own (or with the help of the friendly folks from Gaim: #gaim or #wingaim on irc.freenode.net).
In the root of the gaim-ifolder module, we update the patch file to correspond with the latest version of gaim (i.e., gaim-1.3.1.patches). Get the Gaim source code that corresponds with the latest available patch file. At the time of writing this, the latest version of Gaim was 1.3.1.
Get the Gaim sourcecode for Gaim from CVS
cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/gaim login
Just hit enter for the password.
cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/gaim checkout \ -r v1_3_1 -d gaim-1.3.1 gaim
This will checkout Gaim Version 1.3.1 into a new directory named "gaim-1.3.1".
Patch the Gaim sourcecode to include the Gaim iFolder Plugin
cd gaim-1.3.1
mkdir plugins/gifolder
cp -r <Path to the gaim-ifolder module>/gifolder/* plugins/gifolder
patch -p0 < <Path to the gaim-ifolder module>/gaim-1.3.1.patches
Build Gaim
Unless you really want to, you will not actually use the Gaim binaries you build here. All you're after is for it to produce a gifolder.so (Linux) or gifolder.dll (Windows), which you'll insert into your real version of Gaim when the build is finished.
Note: Building Gaim in Windows is significantly harder than building Gaim in Linux. Make sure to follow all the directions on Gaim's website for setting up the build environment before attempting to build Gaim in Windows.
Linux:
./autogen.sh make
Windows:
make -f Makefile.mingw install
You may hit a couple of file permission/execute rights problems during the build because the file permissions are set incorrectly on a couple files. If you see this, do the following before restarting the build:
Linux:
chmod 755 gaim-1.3.1/plugins/gifolder/gsoap/linux-2.7/wsdl2h chmod 755 gaim-1.3.1/plugins/gifolder/gsoap/linux-2.7/soapcpp2
Windows
chmod 755 gaim-1.3.1/plugins/gifolder/gsoap/win32-2.7/wsdl2h chmod 755 gaim-1.3.1/plugins/gifolder/gsoap/win32-2.7/soapcpp2
Install the Gaim iFolder Plugin
When the build is complete, there's one file you'll need to copy/install before running Gaim:
Linux (Paths shown here are for NLD with Gaim 1.x):
cp gaim-1.3.1/plugins/gifolder/.libs/gifolder.so /opt/gnome/lib/gaim cp gaim-1.3.1/plugins/gifolder/.libs/gifolder.la /opt/gnome/lib/gaim
Windows:
Copy "gifolder.dll" to "C:\Program Files\Gaim\plugins"
Start/Restart Gaim
Enable the iFolder Gaim Plugin
Go into the Gaim Preferences and select Plugins. Scroll down to the iFolder plugin and make sure that it is enabled.
Plugin Configuration
The plugin configuration page in Gaim is, for the most part, a placeholder at the moment for things that we'd eventually like to implement. Some things work, but don't be surprised if something doesn't quite work as you'd expect it to (this is really alpha-level code).
Using iFolder Gaim File Sharing
If you've just installed the iFolder Gaim Plugin and the iFolder Gaim Domain Thread Service, make sure to restart iFolder and Gaim to make sure the new modules are loaded.
Inside iFolder, you should now be able to create new iFolders inside of the Gaim Domain. Your computer will act as the iFolder Server for all iFolders you create inside of the Gaim Domain. In other words, remote computers will synchronize with your computer to get updates to the shared iFolders.
The member/user list for the Gaim Domain (i.e., the list of users who you can share iFolders with) is built by enabling buddies as iFolder users in Gaim. You do this by enabling them from the Gaim Buddy List. Simply right-click on a buddy, and select, "Enable iFolder File Sharing". This will send them an invitation to join your iFolder Gaim Domain (be added as an iFolder user). If the "Enable iFolder File Sharing" option does not appear when you right-click on a buddy, that means they do not have the iFolder Gaim Plugin installed/enabled. Point them to this document if that is the case and help them get it installed.
When a buddy accepts your invitation to be enabled as an iFolder User they will be added into the list of users you'll be able to share iFolders with. You can now use the standard iFolder Client to add the new iFolder user as a member of one of your iFolders.
Note: Not much testing has been done, if any, with disabling a user as an iFolder user. If you see issues with this, please log a bug.
Public Shared iFolder Feature
The Public Shared iFolder feature is intended to make iFolder sharing in Gaim easier. With this feature enabled (enable and disable this in the iFolder Gaim Plugin preferences) an iFolder is automatically created on your desktop. Any and all Gaim buddies that you enable to participate in your iFolder Gaim Domain will automatically be added as Read Only members of this iFolder. This makes it so that all you have to do to share files with everyone is to drag and drop (or create) files in this folder and everyone else in your Gaim Domain will automatically get these files.
Right now, there is no way to exclude an enabled iFolder user from being added to the Public Shared iFolder. Depending on the feedback we get on this, we may or may not add that as a feature. Please let us know what you think!
FAQs/known problems/issues
Will not work through a Firewall
The iFolder Gaim File Sharing solution does not work through a firewall yet. iFolder opens a randomly generated port number (which you can see when you start iFolder from the command-line).
Both machines that you intend to share iFolders between must be able to see each other. Each one acts as a server and client. If a firewall exists between the two computers, both iFolder ports (really it's the Simias processs that opens the port) must be opened.
We are investigating a UPnP solution which would allow iFolder to request for ports to be opened using many popular home routers. We do not have any plans set in stone, however, as to when this feature will be added.
Public Shared iFolder name is fixed
You cannot control the name of the automatic "Public Shared iFolder" that is created on your desktop automatically. This is a limitation in the core iFolder code that will be fixed eventually. If you do not wish to have this automatically maintained public iFolder, disable this feature in the iFolder Gaim Plugin preferences (the last checkbox on the preferences screen).
It would be optimal to allow the user to specify the name and location of this automatically maintained iFolder. Additionally, it would be great if remote users could name the folder on their computers whatever they wanted. This should also be addressed in the future.
There is a bug filed against this problem. You can track it by adding yourself to the CC list:
https://bugzilla.novell.com/show_bug.cgi?id=75454
I have deleted my Simias Store (~/.local). Will I still be able to access the iFolders my buddies shared with me?
No (Partially yes too...read on).
When you deleted your Simias Store, you broke the shared iFolder relationships you previously had configured with other buddies. Additionally, your membership in their shared iFolders was also broken because you no longer have the needed information to connect with their computer again.
Here's the "partial yes" part. The data that you downloaded previously will still be on your own hard drive so you'll still be able to access those files. The folder will no longer be an iFolder. It will not synchronize with the remote buddy's computer either.
To rejoin a buddy's iFolder, you'll have to have them remove your old user as a member of the iFolder and then add you back in. This will cause a new iFolder subscription/invitation to be sent to you, which you'll be able to join again.
I'm using a laptop. What happens if my IP address changes?
This is where the iFolder Gaim Plugin is the most valuable. When you sign back into Gaim after an IP address, the plugin will exchange new IP address information with other buddies who are online (only those buddies who you've enabled as iFolder Users). As soon as this exchange has occurred, iFolders will synchronize as usual.
Note: If you change the location of your computer to a new IP address behind a filewall as described in issue #1 above, iFolder will not be able to synchronize with other computers even though the plugin will be able to provide your update IP address.
What Gaim protocols can be used?
Only the AOL Instant Messenger (AIM/Oscar) protocol can be used right now. The plugin has to publish information in your buddy profile for remote users to know that you've got the iFolder Gaim Plugin installed. Each protocol handles the buddy profile information differently. Since AIM seems to be the most popular, from our standpoint, we chose to use it initially.
Note: Something we have not tested is setting up multiple AIM accounts in Gaim and using the iFolder Gaim Plugin. It is highly likely that you will run into issues and that only one of the accounts will be enabled and usable in iFolder. This configuration will not be supported for the forseeable future.
