 
 Project:   ICQv7-t, ICQv7-transport for Jabber
 URL:		http://icqv7-t.sf.net					
 Version:   0.1.2
 License:   GPL
 Contacts:  Alex_, <alex_@unis-ru.com>

1. Review
~~~~~~~~~

 ICQv7-t is built on top of libicq2000 (ickle project, http://ickle.sf.net),
 and now tries to support all of its functionality. Version numbers of
 ICQv7-t is inherited from ickle ones. At the moment ICQ-related stuff
 ICQv7-t supports include:

   * messaging (through server only)
   * presence notification

 ICQv7-t software consists of two parts:
   * internal part: 

       It works as runtime loaded into jabberd shared object. 
       The internal part is based on old icq-transport 0.9.x code, which
  	   was heavily adapted to fit for new functionality.  
  
       The internal part is responsible for all jabber(d)-related stuff:
		- saving contact list and registration info by the means 
			of xdb-backend,
 		- and so on ;)

   * external part:
		
	   The external part is separate process, which communicates with jabberd
  	   by using JECL infrastructure (jabber.tigris.org). The external part 
	   incapsulate ICQ-related stuff. It's linked with libicq2000 and
 	   handles ICQ-events.


2. Installation
~~~~~~~~~~~~~~~

 Package content:
 
  Until libicq2000 isn't forked into separate project from the Ickle one,
  ICQv7-t package includes its sources. ICQv7-t also includes some nessecary 
  JECL sources, which were slightly modified in some aspects.

 Prerequirements:
  * jabber-1.4.2

	 ICQv7-t does *not* work with jabberd-1.4.1 (because of JECL), so to 
     compile and run ICQv7-t you will need version 1.4.2-test of jabberd.

	 NOTE: if you definitely desire use ICQv7-t with jabber-1.4.1
     see http://icqv7-t.sf.net/#j141

  * gcc-2.95.4+ (gcc-3 recommended)

     Unfortunately, ICQv7-t cannot be built on RH6.2 systems. egcs-1.1.2
 	 catches 'Internal compiler error'. 

     gcc-2.95.3 can compile the transport but then you experience
     sudden segfaults.

  * libsigc++-1.0.0+
  
     It's needed to compile libicq2000

 Installation process
 
   As usually: ./configure && make
   (btw, configure will demand to provide a path to jabber-1.4.2-test sources)

   If you're gonna send complaints plz --enable-debug

  'make install' is *not* provided now, so don't run it.

   After compile you should get two binaries:

          ./jabberd/icqv7t.so  <- internal part 
          ./icqv7ext           <- external part

   Now let's configure


3. Configuration
~~~~~~~~~~~~~~~~

 To configure you need to know at least 3 constants:
	- [internal_jid]

			JID of internal part of ICQv7-t (for example, icq.jabber.org).
			If you want ICQv7-t to be reachable from users of other
 			jabberd-servers, [internal_jid] should be proper FQDN.

    - [external_jid]

			JID of external part of ICQv7-t. I suggest it to be one word 
			(e.g. 'icqv7ext')

    - [sms-t jid]

			JID of sms-transport (for example, sms.jabber.org).
			Should be FQDN if you plan ICQv7-t to be reachable from users
			of other jabberd-servers.

    - [absolute path to icqv7t.so]

 Now let's start configuration.
 In your jabber.xml file do the following:
 
 * Insert info about ICQv7-t into <browse> section:

 <jsm>
     ......... skiped
 	<browse>
  		<service jid="[internal_jid]" name="ICQv7 Transport">
			<ns>jabber:iq:register</ns>
			<ns>jabber:iq:gateway</ns>
 		</service>
	</browse>
 </jsm>

 * Insert configuration for the internal part:

  <!-- First, internal part: -->

  <service id="[internal_jid]">    
	<icqtrans xmlns="jabber:config:icqtrans">
	  <!-- This tag contains the message displayed to users at registration time. -->
      <instructions>Please enter your ICQ number (in the "username" field) and password.  ICQv7-t is not supposed to create new UINs, 'cause its purpose is to provide smooth migration from ICQ to Jabber (i.e. open IM-technologies).</instructions>
      <vCard>
        <FN>ICQ Transport</FN>
        <DESC>This is ICQv7 Transport</DESC>
        <URL>http://icqv7-t.sf.net/</URL>
      </vCard>
      <prime>501</prime> <!-- number of users you expect to use this transport, 
							  should be prime -->

		<!-- the internal part should know jid of the external one -->
	  <external>[external_jid]</external>
  	  <sms>[sms-t jid]</sms>
				
	</icqtrans>
	
	<load>
	  <icqtrans>[absolute path to icqv7t.so]</icqtrans>
	</load>
  </service>

 * Insert configuration for the external part:

  <!-- Second, the external part -->

  <service id='[external_jid]'>

 <!-- JECL specific: -->
    <accept>
      <ip/>
	
 <!-- port which jabberd will listen, and the external part will connect to -->
      <port>7000</port>
 <!-- password to authenticate external part -->
      <secret>mysecret</secret>
    </accept>
 <!-- End of JECL specific -->


 <!-- ICQ-specific: -->
	<[external_jid] xmlns='jabber:config:[external_jid]'>
	  <!-- Configuration for external part: -->
	  
	  <!-- ICQ uses onebyte charsets, but jabber uses UTF8,
	       so one onebyte ICQ sequence can be recoded into several UTF8 sequences
	       (for example onebyte sequence can be recoded into Latin1-part of UTF8,
            or into Cyrillic one)

	       In order to eliminate this ambiguity, we need to specify the charset used
           by ICQers with the same native language. Usually it will be "cp<CODEPAGE#>",
	       where CODEPAGE# is number of codepage in MS Windows for your local character set.
	            For example:
	                 Cyrillic:        cp1251
	                 Latin1:          cp1252
	  -->

	  <!-- Default is 'cp1252' as it was in old icq-transport 0.9.x -->
	  <charset>cp1251</charset>
	 
	  <!-- id of the internal counterpart -->
      <internal>[internal_jid]</internal>

	  <!-- id of sms-t -->
  	  <sms>[sms-t jid]</sms>

      <!-- how to show status of SMS contacts.
		   If absent assumed as unavailable.
           Proper values:
                 chat  (recommended, 'cause usually unused status)
				 away
				 xa
				 dnd
           If empty ( <smsshow/> ) then contacts will be shown as 'online' -->
	  <smsshow>away</smsshow>

	  <!-- whether icqv7-t should reconnect on loosing connection to AOL -->
	  <reconnect/>
        		
	

	</[external_jid]>
  </service>  

 * Configuration for SMS-t

  <service id='[sms-t jid]'>
    <accept>
      <ip/>
      <port>7001</port> <!-- should be +1 to port of external part!! -->
      <secret>mysecret</secret> <!-- should be the same as for external part!! -->
    </accept>
  </service>


4. Run
~~~~~~

 Now start your jabberd, internal part will be initialized.

 When run external part
 ./icqv7ext -n <external_jid> -s <password> -h <jabberd_ip> -p <jabberd_port> -m <sms-t jid>

 	<external_jid>   see above
	<password>		 password you specified in jabber.xml (mysecret)
	<jabberd_ip>	 IP of host running jabberd, try 127.0.0.1 and be surprised
	<jabberd_port>	 port you specified in jabber.xml	  (7000)
	<sms-t jid>      see above
 
	(Default values: icqv7ext:mysecret:127.0.0.1:7000:sms.localhost are hardcoded 
	into main.cpp)


5. Usage
~~~~~~~~

 You can use xdb-base of old icq-transport-0.9.x with ICQv7-t painlessly.

 To use SMS transport:
   add user 
      <mobile_number>@[sms-t jid] and send messages to him.

   <mobile_number> is in form (state_code)(area_code)(...), 
    e.g. for number 
        +7 910 XXX XX XX, 
    <mobile_number> will be 7910XXXXXXX (w/o '+' sign!)
    

6. BUGS
~~~~~~~

 There're some bugs inherited from libicq2000-0.1.2. They will be fixed
 at the next iteration. 


7. Credits
~~~~~~~~~~ 

   Barnaby Gray <barnaby@beedesign.co.uk>     / libicq2000
											  / http://ickle.sf.net

   Schuyler Heath <sheath@jabber.org>         / old icq-transport 0.9.x
  
   Alexandre N. Safiullin <alex_@unis-ru.com> / idea and implementation
											  / of ICQv7-t
											  / http://icqv7-t.sf.net

8. Licensing
~~~~~~~~~~~~

  ICQv7-t uses unusual licensing: portions of code are distributed under
  different licenses, though all of them are open source :)

  Internal part of ICQv7-t
  ~~~~~~~~~~~~~~~~~~~~~~~~ 
   binary: icqv7t.so
   code located in 'jabberd' subcatalog

   The license is JOSL. It's so, because my code is derived from old 
   icq-transport by Schuyler Heath <sheath@jabber.org> and others. 
   My modifications are done in accordance with JOSL.

  External part of ICQv7-t
  ~~~~~~~~~~~~~~~~~~~~~~~~
   binary: icqv7ext
   code located in top source catalog

   The license is GPL. It's because of my preferencies and the fact that 
   code of external part uses libicq2000 which is GPLed.

   Btw, the external part also is linked with JECL, but it is not 
   violation of GPL or JOSL, 'cause COPYING.notes.

  libicq2000
  ~~~~~~~~~~
   code located in 'libicq2000' subcatalog

   GPLed libraries from ickle (ickle.sf.net) project.


  JECL
  ~~~~
   code located in 'libjax', 'libbedrock' & 'libjudo' subcatalogs

   Libraries from the appropriate project (jabber.tigris.com). My little
   modifications of them are done in accordance with JOSL.

  
  libjabber
  ~~~~~~~~~
   code located in 'libjabber' subcatalog

   JOSLed code from jabber.org's jabberd-server. My little
   modifications of it are done in accordance with JOSL.

