-*-Text-*-
This is an RVP (Microsoft Exchange Instant Messaging) plugin for Gaim
1.5 and Pidgin 2.x. It's based on some work done at Lucent - see
AUTHORS file for previous authors of parts of this. Most of the
original codebase has been replaced.

Note, this code ONLY supports RVP. It does not support SIP or .NET
messaging.

INSTALLATION:
See the INSTALL file for build and install instructions.

CONFIGURATION:
The less config you use, the better, I've found. Start Gaim and select
Add Account, then select RVP from the pulldown list. Put your
username@domainname into the Screen Name field. Then select the "Show
More Options" arrow, and put in your Windows domain in the Auth Domain
field. This should be sufficient for most scenarios. The other options
on this screen are as follows:

  * Password: ...
  * Alias: not used by RVP. The server's value overrides this.
  * Auth Host: RVP tries to figure out which host it should talk
    to. If it can't figure out your IM host for any reason, put the IM
    hostname in here.
  * Auth ID: if your screen name and login name differ, put the login
    name here. This is a highly unlikely scenario, mind you.
  * My Hostname: RVP tries to figure out the hostname it should offer to
    the IM server for routing messages to you. Since this predates
    UPnP, it's possible that RVP will get it wrong if you're behind a
    firewall or network translation layer. In that case, put the
    correct hostname in here. Again, I'd rather this wasn't used as
    there's an option in Gaim's Network Preferences to do the same
    thing.
  * Proxy: I've never tested this code via a proxy, so I have no idea
    if it works or even how it should work. 

On Pidgin 2 there's an option (default true) to use the local IP rather
than any detected UPNP address. You probably want this, as it's not
likely that your RVP server lives on the public Internet.

WHAT WORKS...

* Instant messaging works.
* Group chats work, but Gaim's chat is a poor fit with Microsoft's. To
  initiate a multi-user chat, use the Add Chat menu option to add a
  blank chat to your buddy list, then double-click it to open it and
  invite as many users as you like. If someone you are IM'ing invites
  a third party to the conversation, you will get a new window for the
  chat. This may improve in future versions.
* File transfer works in both directions, although Microsoft's client
  offers two ports to connect to while I only work with one. This
  hasn't yet caused me any problems.
* Incoming messages with font and colour are dealt with as best your
  locally installed fonts can manage.
* Away status works, albeit without sending automatic messages to
  anyone who tries to talk to you while you're away.

...AND WHAT DOESN'T:

* Gaim imposes a few restrictions that I'd rather didn't exist, or
  that I've not yet figured out how to escape. This is why
  conversations with people not on your buddy list use their login ids
  instead of real names, and why multi-user chats have weird
  hexadecimal titlebars.
* Application Sharing, Voice Calls, and Whiteboarding are all
  implemented using Netmeeting. I have not even tried to figure out
  how to do any of this. Whiteboarding actually looks to be a
  specialised version of Application Sharing using MS Paint.
* Send Email is very rough and could do with more work once I figure
  out how I'm really supposed to invoke GNOME's configured apps.
* The Get Info page is a little rough, and doesn't work on
  non-buddies.
* Setting fonts and colours on outgoing messages isn't implemented,
  largely due to a mismatch between what Gaim allows and what
  Microsoft allows.
* Polling connections aren't supported, as I've not reverse-engineered
  the protocol and Microsoft has deprecated it.
* There is a small amount of weirdness with Auto-Away vs. manual away
  at least on Gaim 1.5; Pidgin appears to have a small amount of
  weirdness with respect to not recognising self-subscriptions
  properly when updating the buddy list.

See the to-do list at the end of the file for things that I plan on
fixing up.

I FOUND A BUG. WHAT DO I DO?

Until such time as there's a 1.0 release (and, realistically, beyond
that), it's safe to assume that there are bugs in this code. If you
find a bug, and you can reproduce it, run gaim with the --debug flag
and capture the output to a file. Send me this file along with a rough
description of what happened. Edit it as you see fit to obscure
personal/corporate/private information, but please try to keep the
debugging information intact.

TO-DO LIST:
- See ChangeLog for a list of what's been changed/fixed recently.
* general
  - get 2.0 code cleaned up and working
    - mostly working at this point, although there are rough
      edges, since the codebase was swiftly ported to Pidgin after the
	  name-change. I really need to clean this up.
      - file transfer is more than likely broken in 2.0
  - url send is not safe! (doesn't check write() return code) This is
    sort of a big deal since url send is how it all works, but if it's
	broken you'll probably find a lot of other things are broken too,
	and IM will be the least of your worries.
* clean up multi-user chat
  - figure out the circumstances under which the title is set/unset
  - part of shutdown sequence should send a chat signoff to any active
    chats
  - 'add buddy to this chat' would be great, even though gaim doesn't
    really support it
* user context menu
  - Send Email - there, but rough
  - Properites - there, but rough
* match MSM look/feel more closely (icons, etc.)
  - outgoing font/colour (Gaim 1.5 has good support for this)
  - custom permissions UI to match MSM client would be nice
* implement POLL
  - haha. microsoft have actually abandoned this because it was
    causing them a huge amount of support calls.
* figure out how to do a working shutdown sequence
  - add overall shutdown timeout
  - maybe display some sort of progress?
  - not happy that it requires an explicit call to gtk's event loop
* file transfer
  - code needs cleaning up in general, since it was implemented
    optimistically.
  - not all BYE codes are handled at present
  - add timeouts
  - 'send file to myself' doesn't work, and should either error out or
    try to do something sane (send file to other instance of myself,
	perhaps). It definitely shouldn't crash Gaim in any of the ways it
	currently does.
  - if xfer is accepted, ignore subsequent reject attempts. this
    caters for sending to a recipient logged in from multiple
	locations.
