Contacts Importer for PHP/.NET/Java/Ruby User Manual

Copyright © 2008 Octazen Solutions. All Rights Reserved.

Table of Contents

• Supported address books
• General notes
• System Requirements
• Installation / Files in Distribution
• Logging
• Optimizing

Supported Address Books

Note that Ruby version supports only Hotmail, Yahoo, Gmail and AOL

General Notes

• To defend against automated attacks/misuse of the library, it is HIGHLY RECOMMENDED that you place some sort of Captcha or limiter on your web page using this library.
• Thread safety: When using the individual importers (GmailImporter, HotmailImporter, etc) please remember to create one instance for each import request as these importer objects would maintain state of the web session. (This is not an issue as it is done automatically for you if you follow the samples codes that we provide)

Requirements

PHP

• PHP 4.3 or higher (PHP 4.4 or better recommended)
• cURL 7.1 or higher (7.10 or higher required for compression support)
• OpenSSL
• mbstring or iconv modules required if using Mail.ru. Note: IConv is bundled with PHP 5.

.NET

• .NET Framework 2.0
• Website running in full trust. (If you are running the website in partial/medium trust mode, ensure proper trust is granted on the DLLs)

Java

• Java 5 or higher (Java runtime 1.4 or higher supported via Retroweaver)
• Apache commons-logging is used for logging

Ruby

• Ruby 1.8 or higher
• Mechanize & hpricot. To install these modules, issue the following commands
  • gem install mechanize --include-dependencies

ColdFusion

• ColdFusion MX 7 or higher
• Java 1.4.2 or higher

Installation/Files in Distribution

PHP

Not all files are present. Some files are available only in specific bundles.

Standard Install

To install, simply upload the contents of the following files to your server, maintaining the folder structure. Please note that the folder structure should be as follows. Also note that some files under the abimporter directory may not be available in your bundle.

importer.php
importercsv.php
recaptchalib.php
abimporter/abi.php
abimporter/abiconfig.php
abimporter/abimporter.php
abimporter/oz_ldif.php
abimporter/oz_csv.php
abimporter/aol.php
abimporter/fastmail.php
abimporter/gmail.php
abimporter/gmx.php
abimporter/hotmail.php
abimporter/icq.php
abimporter/indiatimes.php
abimporter/linkedin.php
abimporter/lycos.php
abimporter/macmail.php
abimporter/maildotcom.php
abimporter/mynet.php
abimporter/rediff.php
abimporter/webde.php
abimporter/yahoo.php
abimporter/mailru.php
abimporter/freenetde.php
abimporter/interia.php
abimporter/libero.php
abimporter/onet.php
abimporter/rambler.php
abimporter/yandex.php
abimporter/plaxo.php

PHPFox Installation

Important! The PHPFox mod modifies PHPFox's existing invitation engine. You may want to perform a backup of your existing PHPFox files before installing our component.

Copy the contents of phpfox/1.5/* or phpfox/1.6/* to your PHPFox installation. Use phpfox/1.5 contents if you're using PHPFox 1.5, and phpfox/1.6 contents if you're using PHPFox 1.6

Due to PHPFox's use of compiled Smarty templates, you may need to touch (edit and save) the file /design/templates/default/_modules/Account/InviteFriend.html so that Smarty picks up the changes and recompiles the HTML template.

.NET

Java

Ruby

Installation involves only the inclusion of the necessary *.rb files. See testimporter.rb for details.

ColdFusion

Installation involves uploading importer.cfm, importercsv.cfm, lib folder and javaloader folder contents into your web application.

Library has been tested on the following configuration

• ColdFusion MX 7 & 8
• JRun4 (ColdFusion's built in web container) & IIS
• Java 1.4.2 & 6 Runtime

To enable logging, you may want to follow these steps http://kb.adobe.com/selfservice/viewContent.do?externalId=tn_18249 . You may require administrator access for this.

To enable detailed http tracing, copy the log4j.properties into your ColdFusion's runtime/servers/lib folder. You may require administrator access for this.

Usage

To use the library, use the following code as a base.

NOTE! Please see the sample codes that came with this package for the most up-to-date samples.

<?php

include_once("abimporter/abi.php");  //This includes the individual importers and relevant files

$obj = new AddressBookImporter;
$res = $obj->fetchContacts($email,$pass);
if ($res==_ABI_AUTHENTICATION_FAILED) {
    echo 'Bad user name or password';
}
else if ($res==_ABI_FAILED) {
    echo 'Server error';
}
else if ($res==_ABI_UNSUPPORTED) {
    echo 'Unsupported webmail';
}
else if ($res==_ABI_CAPTCHA_RAISED) {
    echo 'Captcha challenge raised for login';
}
else if ($res==_ABI_USER_INPUT_REQUIRED) {
    echo 'User needs to answer some questions in the webmail service';
}
else if (is_array($res)) {
    foreach ($res as $contact) {
        $name = $contact->name;
        $email = $contact->email;
        echo htmlentities($name).' <'.htmlentities($email).'><br>';
    }
}
else {
    echo 'Unknown error';
}
?>

using System;
using System.Collections.Generic;
using System.Text;
using Octazen.AddressBook;
using Octazen.Http;
using Octazen.Debug;
using Octazen.Captcha;

namespace AbiTester
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                string email = "myaccount@gmail.com";
                string pass = "mypassword";
                List<Contact> cl = 
                    SimpleAddressBookImporter.FetchContacts(email, pass);
                foreach (Contact contact in cl)
                    Console.WriteLine(contact.Name+ " <" + contact.Email + ">");
            }
            catch (UnsupportedAddressBookException e)
            {
                Console.WriteLine("Unsupported webmail");
            }
            catch (CaptchaChallengeException e)
            {
                Console.WriteLine("Captcha challenge was raised - " + e.Message);
            }
            catch (UserInputRequiredException e)
            {
                Console.WriteLine("Need to answer some questions in the webmail service - " + e.Message);
            }
            catch (AddressBookAuthenticationException e)
            {
                Console.WriteLine("Authentication failed - " + e.Message);
            }
            catch (Exception e)
            {
                Console.WriteLine("Server error - " + e.Message);
                Console.WriteLine(e.StackTrace);
            }
        }
    }
}

import java.io.IOException;
import java.util.Iterator;
import java.util.List;
import octazen.addressbook.AddressBookAuthenticationException;
import octazen.addressbook.AddressBookException;
import octazen.addressbook.Contact;
import octazen.addressbook.SimpleAddressBookImporter;
import octazen.addressbook.UnexpectedFormatException;
import octazen.addressbook.UnsupportedAddressBookException;
import octazen.http.HttpException;
import octazen.http.UserInputRequiredException;
import octazen.captcha.CaptchaChallengeException;

public class TestImporter {
    public static void main(String[] args) {
        try {
            String email = "myaccount@gmail.com";
            String pass = "mypassword";

            List<Contact> list = 
                SimpleAddressBookImporter.fetchContacts(email, pass);
            Iterator<Contact> it = list.iterator();
            while (it.hasNext()) {
                Contact contact = (Contact) it.next();
                System.out.println(contact.getName() 
                    + " <"+ contact.getEmail() + ">");
            }
            } catch (AddressBookAuthenticationException e) {
                System.err.println("Sorry, bad user name or password");
            } catch (UnexpectedFormatException e) {
                System.err.println("Server error. Received unexpected content");
            } catch (UnsupportedAddressBookException e) {
                System.err.println("Unsupported webmail");
            } catch (CaptchaChallengeException e) {
                System.err.println("A captcha challenge was raised");
            } catch (UserInputRequiredException e) {
                System.err.println("Need to answer some questions in the webmail service");
            } catch (AddressBookException e) {
                System.err.println("Unsupported webmail / internal error");
            } catch (IOException e) {
                System.err.println("IO exception:" + e.getMessage());
            } catch (HttpException e) {
                System.err.println("General http error");}
    }
}

# Sample code demonstrating use of Ruby importer

require 'abimporter/abimporter'
require 'abimporter/yahoo'
require 'abimporter/gmail'
require 'abimporter/hotmail'
require 'abimporter/aol'


obj = Octazen::GmailImporter.new
#obj = Octazen::YahooImporter.new
#obj = Octazen::HotmailImporter.new
#obj = Octazen::AolImporter.new


begin
	al = obj.fetch_contacts("myemail@domain.com","mypassword")
	
	al.each do |contact|
		email = contact.email
		name = contact.name
		puts "Email=#{email}, Name=#{name}"
	end

rescue Octazen::AuthenticationError => err
	puts "Bad user name or password"

rescue Octazen::UnexpectedFormatError => err
	puts "Server returned unexpected data"

rescue Octazen::CaptchaError => err
	puts "Captcha challenge issued by server"
	
rescue Octazen::UserInputRequiredError =>; err
	puts "Need to answer some questions in the webmail service"

rescue Octazen::AddressBookError => err
	puts "General error"
	
end

For ColdFusion, see sample script importer.cfm

Importing from Outlook / Outlook Express

The Address Book Importer library supports importing of contacts from Outlook & Outlook Express' exported CSV files. The library does not support Outlook Express' WAB file format at the moment. Note that the library supports only CSV files with English headers for now. Support for headers in other languages is currently under development.

Note that this library provides the codes to parse the CSV files, but not the code to handle the CSV file uploading itself. Note that the same exceptions as shown in the above code is thrown on errors.

This feature is currently not available in the ColdFusion version

$csv = ""; //Put your actual CSV content here.
$res = abi_extractContactsFromCsv($csv);
//$res is the same return result as $obj->fetchContacts(...)

String csv = ""; //Put your actual CSV content here.
List<Contact> cl = octazen.addressbook.FileImporter.ExtractContactsFromCsv(csv);

String csv = ""; //Put your actual CSV content here.
List<Contact> cl = octazen.addressbook.FileImporter.extractContactsFromCsv(csv);

Importing from Thunderbird (CSV)

The Address Book Importer library supports importing of contacts from Mozilla Thunderbird's exported CSV.

Note that this library provides the codes to parse the CSV files, but not the code to handle the CSV file uploading itself. Note that the same exceptions as shown in the above code is thrown on errors.

This feature is currently not available in the ColdFusion version

$csv = ""; //Put your actual CSV content here.
$res = abi_extractContactsFromThunderbirdCsv($csv);
//$res is the same return result as $obj->fetchContacts(...)

String csv = ""; //Put your actual CSV content here.
List<Contact> cl = octazen.addressbook.FileImporter.ExtractContactsFromThunderbirdCsv(csv);

String csv = ""; //Put your actual CSV content here.
List<Contact> cl = octazen.addressbook.FileImporter.extractContactsFromThunderbirdCsv(csv);

Importing from Thunderbird (LDIF)

The Address Book Importer library supports importing of contacts from Mozilla Thunderbird's exported LDIF.

Note that this library provides the codes to parse the LDIF files, but not the code to handle the LDIF file uploading itself. Note that the same exceptions as shown in the above code is thrown on errors.

This feature is currently not available in the ColdFusion version

$ldif = ""; //Put your actual LDIF content here.
$res = abi_extractContactsFromLdif($ldif);
//$res is the same return result as $obj->fetchContacts(...)

String ldif= ""; //Put your actual LDIF content here.
List<Contact> cl = octazen.addressbook.FileImporter.ExtractContactsFromLdif(ldif);

String ldif = ""; //Put your actual LDIF content here.
List<Contact> cl = octazen.addressbook.FileImporter.extractContactsFromLdif(ldif);

reCaptcha

The sample code by default, makes use of reCaptcha to ensure that the library cannot be misused by third party scripts.

You are free to swap, or remove the existing Captcha algorithm and roll your own.

Binding to Specific Local Network Interfaces

If you server runs on multiple IP addresses, the library allows you to bind to specific local network interfaces. You may use this to perform "load balancing" across several IP addresses. This is normally desirable only if are expecting large number of users.

//Simply define the local ip address to bind to prior to using library
$GLOBAL['_ABI_INTERFACE'] = "202.190.202.100";

//Set bind point
IPAddress[] aa = Dns.GetHostAddresses("202.190.203.200");
IPEndPoint prev = HttpSocketBindPoint.SetBindPoint(new IPEndPoint(aa[0], 0));

//Make use of library
//...

//Restore previous bind point (or use null)
HttpSocketBindPoint.SetBindPoint(prev);

//Set bind point
SocketAddress prev = HttpSocketBindPoint.setBindPoint(new InetSocketAddress("202.190.203.200",0));
        
//Call library
//...

//Restore previous binding point (or use null)
HttpSocketBindPoint.setBindPoint(prev);

Configuring Timeouts

You may want to configure connection and socket timeouts. Please follow these instructions for doing so :.

//Number of seconds to wait whilst trying to connect, 0 for indefinitely. Default 20.
$GLOBAL['_ABI_CONNECTTIMEOUT'] = 20;
//Number of seconds curl is allowed to execute. Default 60.
$GLOBAL['_ABI_TIMEOUT'] = 60;

//Set send and receive timeout in milliseconds. -1 or 0=infinite
HttpSocketFactory.GetDefaultInstance().SendTimeout = 60000;
HttpSocketFactory.GetDefaultInstance().ReceiveTimeout = 60000;

//Set socket timeout in milliseconds
HttpConnectionManager.getDefaultInstance().setSoTimeout(60000);
//Set connect timeout in mimlliseconds (0=infinite)
HttpSocketFactory.getDefaultInstance().setConnectTimeout(20000);

Alternative Http Library

The Java version supports either raw sockets (default) or Java's HttpUrlConnection as the underlying Http library. Raw sockets allows binding to specific local interfaces but has no support for proxies. HttpUrlConnection allows Java's proxy support to be used, but does not allow binding to specific local interfaces. To switch to HttpUrlConnection, execute the following code before using the library.

HttpRequestorFactory.setDefaultInstance(new UrlHttpRequestorFactory());

You may use Java's system properties to define the necessary proxies. You may also make use of the Proxy class by performing the following

• Derive a class from UrlHttpRequestorFactory, say MyUrlHttpRequestorFactory
• Derive a class from UrlHttpRequestor, say MyUrlHttpRequestor.
• Override UrlHttpRequestor's "protected HttpURLConnection createHttpUrlConnection(String url)" to return an HttpURLConnection using the necessary Proxy class.
• Override UrlHttpRequestorFactory's method "public HttpRequestor newRequestor(String url, HttpState state)" to return a new instance of MyUrlHttpRequestor
• Call "HttpRequestorFactory.setDefaultInstance(new MyUrlHttpRequestorFactory());" before making use of the library

For more information, please contact us at support@octazen.com

Logging

Java

The Address Book Importer library uses the Apache Commons Logging library, and performs extensive logging by default. (Mostly FINEST/TRACE/DEBUG logs). Commons Logging library is a facade for other logging facilities such as log4j and JDK 1.4's built in logging mechanism.

To reduce or turn off logging for the address book importer, follow these steps.

If you're using log4j,
You can configure your log4j.properties file to set the logging level appropriately for the package level named "octazen" to WARN.
Refer to log4j's documentation on this.

If you're using JDK's built-in logging mechanism

You need to do 2 things
1) Declare a system properties "java.util.logging.config.file" to point to your logging.properties files
2) Create a logging.properties file with the following content. This will set all Octazen libraries to log only warning/error messages

handlers = java.util.logging.ConsoleHandler
octazen.level=WARNING
java.util.logging.ConsoleHandler.level = FINEST
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
     
Setting logging level to FINEST / TRACE would be useful only if you encounter problems, and would like
to pass us the web conversation log to troubleshooting purposes.

Optimizing

The library by default makes use of HTTP 1.0 with no connection keep-alives. You can enable keep-alives by executing the following code prior to using the library. Note that Http keep-alive option is only available for .NET and Java, and is applied at class (static) level.

Octazen.Http.WebRequestor.EnableHttp1_1Features(true);

octazen.http.WebRequestor.enableHttp1_1Features(true);

Enquiries & Issues

If you have any enquiries, issues, or bug reports, please email us at support@octazen.com