Time-stamp: <2001-07-16 15:38:19 Administrator>
--------------------------------------------------------------------------
What is IMCom
IMCom is console Jabber Client written in Python. It in many ways
resembles micq because that is the ICQ client that I used before
switching to jabber.
--------------------------------------------------------------------------
What does IMCom require
IMCom first and foremost requires a python interpreter which can
be obtained at www.python.org. I have tested only with python 2.0. It
may work with python 1.x and it may work with python 2.1, I don't know
though. Also, this has only been tested on the linux C Python version
2.0. If someone is willing to test on other platforms/version please
contact me.
IMCom requires the pyexpat or expat module for python. Note that while
the windows binary distribution of python includes the expat parser
the linux source by default doesn't build in support for expat. You
have to edit the Setup file in the Modules subdirectory of the source
tree and specify where the expat library and includes are kept. For
more information about building python with expat support read the
python README and the Modules/Setup.in file from the python source
tree.
The expat library itself can be found here:
http://www.jclark.com/xml/expat.html
It is highly recommended, but not required, to have the readline
module for python installed as well.
Readline needs to be explicitly compiled in under unix.
Windows does not ship with readline, but supposedly there is a working
implementation here:
http://newcenturycomputers.net/projects/readline.html
IMCom supports
* Account Creation
* Roster Management (adding, removing users)
* Status changing
* VCard retrieval (very basic)
* Logging
* Auto-reconnecting on disconnect
* Command and color customization
* Primitive group support
* Transport Registration (icq, aim, msn, etc)
* File Transfer
IMCom does NOT support
* Group Chat
* VCard submission
* Searching for users
* SSL Connections.
------------------------------------------------------------------------
Where can I get IMCom
http://imcom.floobin.cx Documentation
http://imcom.floobin.cx/src Archives
http://discobob.dyndns.org/~crabbkw/imcom/ Bleeding Edge Source
------------------------------------------------------------------------
How do I start IMCom?
There are two programs in the IMCom suite right now,
* the command-line interface, which is started by python CLI.py
* the account-creation utility which is started by
python AccountCreator.py
Note that while the client has been fairly well tested, the
AccountCreator has not.
------------------------------------------------------------------------
How do I use IMCom
IMCom is command driven, the default commands are the following:
/msg /msg airog hello
Sends a message a user. The username can either be a nickname
you have specified or a fully qualified Jabber ID. This has two
modes, single-line mode and multi-line mode. In single-line mode
it takes a username and a message to send. In multi-line mode
hit enter after typing the username and it will display a
different prompt: [msg]: Type a period on a line by itself to
send the message, or a hash( # ) on a line by itself to cancel
the message.
e
Displays a list of users currently online.
w
Displays the status of everyone on your roster.
/info /info airog@jabber.zollers.net
Retrieves the VCard of a user. It will display only the
Fullname, Given Name, Family Name and Nick Name. It takes either
a nickname or a fully qualified JID.
/add /add airog@jabber.zollers.net airog
Adds a user to your roster, requesting permission if need
be. The first parameter is the fully qualified Jabber ID, the
second parameter is the nickname to give the JID.
/remove /remove airog
Removes a user from your roster. The user may be specified as a
nickname or a fully qualified Jabber ID.
/online /online
Sets your current status to online.
/chat /chat
Sets your current status to free for chat
/away /away I've stepped out for a minute
Sets your current status to Away with the reason specified.
/xa /xa I'm going to bed
Sets your current status to eXtended Away with the reason
specified. Extended Away is equivalent to Not Available.
/dnd /dnd I'm doing homework
Sets your current status to Do Not Disturb with the reason
specified.
/quit
Quits the program.
// // I'm doing well
Sends a message to the last person you messaged. This command
has similar functionality and options as /msg
/r /r I'm doing well, yourself?
Sends a message to the last person who messaged you. This
command has similar functionality and options as /msg
/set /set colors off
Sets boolean variables as to how IMCom behaves. The boolean
values accepted as true are "true", "yes". Everything else is
interpreted as false. Currently the following variables are
supported:
* statusshow Whether or not to show status updates
* colors Whether or not to use colors
* debug Whether or not to output debugging information
* ringbell Whether or not to ring the terminal bell on incoming msg
/auth /auth airog@jabber.zollers.net
Sends authorization to a user so that they can add you to their
roster. The user may be specified by either nick or fully
qualified Jabber ID.
! ! ls ~
Executes the rest of the line as a command.
/rename /rename airog@jabber.zollers.net casey
Gives a new nickname to a roster item. The first parameter can be
either a nickname or a fully qualified Jabber ID, the second
parameter is literally the new nickname.
/delete /delete airog@jabber.zollers.net
Completely removes all information about a user from your
roster. Note that you can remove people's subscription to your
presence by doing this. This command is not recommended general
use.
/listprofiles
Lists all the profiles currently in the configuation file.
/switchprofile /switchprofile seifer
Switches profile to the named profile.
/show /show lurker
Lists all users in a particular group. Without an argument, lists
all the groups that exist.
/addgroup /addgroup airog lurker
Add a user to a group
/delgroup /delgroup airog lurker
Remove a user from a group
/setgroup /setgroup airog lurker
Set a users group to be just the group specified.
/membership /membership airog
Shows the list of groups a person belongs to.
/agents /agents
Retrieves a list of all transports available on the server.
/agenthelp /reghelp icq.floobin.cx
Gets help on registering for a transport on the server.
This step is REQUIRED in the registration process.
/agentreg /agentreg icq.floobin.cx 1227636 airog yeahright
Registers with a transport on your server. The agenthelp command must
be issued before this command will be successful, the agenthelp command
will tell you the exact format of this command as it changes from time
to time.
/sendfile /sendfile airog /home/crabbkw/testme.txt
Sends a file to a user. The transport MUST support file transfer
for the file to send. ICQ, AIM, MSN transport DO NOT SUPPORT file
transfer.
/getfile /getfile airog
Initiates a file transfer when someone is trying to send you a
file. The file will be saved in ~/.imcom/files
/saveprefs /saveprefs
Saves your preferences.
/alias /alias today ! date
Creates a textual substitution alias. The example above creates
the aliased command today, which runs the date program.
/alias by itself will list the aliases which currently exist
/unalias /unalias today
Removes an existing alias. Remember to save your preferences
after creating or removing an alias
/logs /logs casey
Allows searching logfiles by nick, time/date, or text. The following
rules and caveats apply:
* You can specify the log to search by a list of nicks or jids, and
you can also use the wildcard "*". For instance: /logs casey,*_aim
* The text search feature is case-insensitive if you enter your
query in all lowercase, and case sensitive if you use any
uppercase in your query.
* Dates should be specified in the form 2001-11-21 14:08:15
* two-part times (14:08) are allowed and interpreted minutes and
hours (14:08 becomes 14:08:00)
* two-part dates are allowed and interpreted as mm/dd (american
format). The year is assumed to be the current year and the time is
midnight
* "today" is today at 23:59; "yesterday" is yesterday at midnight
/last /last
In this form the last command will show you people who've messaged
in this session
/last /last casey
In this form the last command will show you the last exchange with
the specified nick
/last /last casey 5
In this form the alst command will show you the last 5 messages sent to
or from the specified nick. This reads the logfiles, so there's no
upper bound on the number of messages
/help
Show the commands available and a brief description of them.
------------------------------------------------------------------------
How do I customize IMCom
IMCom is a very customizable program. The commands and colors are both
completely customizable by tweaking the configuration file. The
configuration file is in pure XML. The following is a complete example
of a configuration file.
<imcom default='jabber.org'>
<command>
<msg>/msg</msg>
<e>e</e>
<w>w</w>
<info>/info</info>
<add>/add</add>
<remove>/remove</remove>
<online>/online</online>
<chat>/online</chat>
<away>/away</away>
<xa>/xa</xa>
<dnd>/dnd</dnd>
<quit>/quit</quit>
<reply>//</reply>
<respond>/r</respond>
<set>/set</set>
<auth>/auth</auth>
<bang>!</bang>
<rename>/rename</rename>
<delete>/delete</delete>
<listprofiles>/listprofiles</listprofiles>
<switchprofile>/switchprofile</switchprofile>
<show>/show</show>
<addgroup>/addgroup</addgroup>
<delgroup>/delgroup</delgroup>
<setgroup>/setgroup</setgroup>
<membership>/membership</membership>
<agents>/agents</agents>
<agenthelp>/agenthelp</agenthelp>
<agentreg>/agentreg</agentreg>
<getfile>/getfile</getfile>
<sendfile>/sendfile</sendfile>
<alias>/alias</alias>
<unalias>/unalias</unalias>
<saveprefs>/saveprefs</saveprefs>
<help>/help</help>
</command>
<profile name='jabber.org' debug='false' statusshow='true'
ssl='false' colors='true' ringbell='true'>
<server>jabber.org</server>
<port>5222</port>
<user>testuser</user>
<password>yeahright</password>
<resource>at home</resource>
<command>
<msg>/msg</msg>
<e>e</e>
<w>w</w>
<info>/info</info>
<add>/add</add>
<remove>/remove</remove>
<online>/online</online>
<chat>/online</chat>
<away>/away</away>
<xa>/xa</xa>
<dnd>/dnd</dnd>
<quit>/quit</quit>
<reply>//</reply>
<respond>/r</respond>
<set>/set</set>
<auth>/auth</auth>
<bang>!</bang>
<rename>/rename</rename>
<delete>/delete</delete>
<listprofiles>/listprofiles</listprofiles>
<switchprofile>/switchprofile</switchprofile>
<show>/show</show>
<addgroup>/addgroup</addgroup>
<delgroup>/delgroup</delgroup>
<setgroup>/setgroup</setgroup>
<membership>/membership</membership>
<agents>/agents</agents>
<agenthelp>/agenthelp</agenthelp>
<agentreg>/agentreg</agentreg>
<getfile>/getfile</getfile>
<sendfile>/sendfile</sendfile>
<alias>/alias</alias>
<unalias>/unalias</unalias>
<saveprefs>/saveprefs</saveprefs>
<help>/help</help>
</command>
<color>
<user>brightgreen</user>
<status>yellow</status>
<error>brightred</error>
<messagebody>cyan</messagebody>
<time>blue</time>
<desc>purple</desc>
<sep>brightblue</sep>
<default>white</default>
<key>green</key>
</color>
</profile>
</imcom>
You do not have to specify all the subelements under command or color,
the defaults will be used for all subelements not appearing. The
command has a section outside profiles. This is the global command
section applying to all profiles. The profile command section will
override the imcom profile section.
The following values are valid for colors:
* darkgray
* brightred
* brightgreen
* yellow
* brightblue
* purple
* brightcyan
* white
* black
* red
* green
* brown
* blue
* magenta
* cyan
* lightgray
The following are subelements of color:
* user the color to use for all JIDs and nicknames
* status the color to use for all status information
* error the color to use when an error occurs
* messagebody the color to use for a message body
* time the color used to display time stamps
* desc the color used for all descriptions
* sep the color used for all separators
* key the color used for keys in key, value pairs
* default the color used by everything else
------------------------------------------------------------------------
What do you mean group support?
Each user can belong to 0 or more groups. To show the groups a
particular person belongs to use the membership command.
Example:
/membership airog
This would return the list of groups the user airog belongs to.
To see which users belong to a particular group use the show command.
Example:
/show lurker
This would return a list which looks very similar to the roster list
except that it only shows users which are members of the group lurker.
To see a list of the groups that you have just use the show command
with no arguments.
Example:
/show
This would return the list of groups currently in existance.
Note that you never actually have to create a group. Simply adding a
user to a non-existing group will create that group.
There is currently one special group. The lurker group is used for
people who you want to have Nick<->JID matching on, but don't want to
see status updates for or even on your roster at all. For instance, I
use the lurker group for people who I have on my list twice, once with
their icq user and once with their jabber user. I add their icq user
to my lurker group so I never see it unless I really want to. I also
use it for people who I very rarely talk to. People who are a member
of the lurker group will only ever show up if you use the show command
to show the members of group lurker. If a user (bob) belongs to both
lurker group and school group, and you use the show command to list
the members of the school group bob will not appear in that list
because he is a lurker. The only list a lurker will show up in is the
lurker list.
To add a user to a group use the addgroup command. It will create the
group if necessary.
To remove a user from a group use the delgroup command. It will remove
the group if no users exist in the group anymore.
To set a user belonging to just one group use the setgroup command. It
will create the group if necessary.
------------------------------------------------------------------------
File Transfer information.
To send a file user: /sendfile airog myfile.txt
To receive a file from a user: /getfile airog
To refuse receipt of a file simply ignore it.
Files are saved in ~/.imcom/files
------------------------------------------------------------------------
$0 through $9
The person who most recently evented you is stored in $0 through $9.
Events include messages, auth requests, file requests, basically everything
EXCEPT status changes.
This is an advanced feature and not yet well tested at of version 0.62.
It is useful when random3409783408@jabber.org messages you because you
can then just
/info $0
To get info on random3409783408@jabber.org.
------------------------------------------------------------------------
Aliases
This is another advanced feature that was requested. Basically aliases
are textual-substitution commands. That is, you can shorten one
command line to a single command. For instance, say you are running on
a unix system and want to bind the command /cls to clear the
screen. You could
/alias /clear ! clear
Which would create the alias /clear, which would literally run
! clear
Let say I message user bob often. I could
/alias /bob /msg bob
which would allow me to
/bob hi!
Sending the message "hi!" to bob.
To get a list of aliases use just
/alias
To remove an alias use
/unalias <alias-name>
eg: /unalias /bob
To save aliases to your preferences issue a saveprefs command, which
defaults to /saveprefs
------------------------------------------------------------------------
Who maintains IMCom
Casey Crabb (crabbkw@rose-hulman.edu) maintains IMCom and
enthusiastically accepts bug reports, especially if they are
reproducible. Feature requests are also taken into consideration and
potentially added to the list of things to do.