Documentation AddressBook Importer DLL OAuth version

The StesCodes AddressBook Importer provides the ability to import contacts from various mail servers in minutes. The code uses oauth external authentication process to authenticate user. The DLL is compatible in both shared and dedicated servers. It also supports .net framework 3.5 and above, also supports C# and VB.net. The below is the technical document to configure the grabber.

<<back to AddressBook Importer OAuth

1 Auto Update
1.1 Parameter
1.1.1 Context
1.1.2 Signature
1.1.3 Bin Location
1.1.4 IM file
2 AddressBook Importer
2.1 Reference
2.2 Function
2.3 Parameters
2.4 Return Type
2.4.1 Collection
2.4.1.1 Members
2.5 Binding
3 Handling Error
3.1 Message
4 Configurations
4.1 Permissions
4.2 Turn On/Off AutoUpdate
5 Change Domain
5.1 Update/edit domain

AutoUpdate DLL

Autoupdate is the first step in configuring StesCodes AddressBook Importer, which will check for updates once every day. Once a update is found, the DLL will download the latest DLL from StesCodes server and update your old DLL automatically. Inorder to perform a manual update, you have to remove a file called "stescodes.im" from your server(which was created to store update info) and start grabbing for any of the service; which will basically force the update process to happen. Most importantly your project should have read/write permission oras per our specification. You shall download the autoupdate DLL by login to StesCodes (http://stescodes.com/sourceupdate.aspx) and download your source code which contains the autoupdate.dll file.

Parameters

Please import namespace "autoupdate"

Parameters	Description	Required?
1. Context	Gets the System.Web.HttpContext object associated with the page	Yes
2. Signature	Signature Key provided during purchase(license key)	Yes
3. Bin Path	The physical path to your bin directory to update the DLL. If this parameter were not passed then the default bin location inside the current directory will be choosen to update the DLL. If IMfile path is provided then the path to bin folder should be provided. eg: D:\myproject\bin (no slash after path)	Optional
4. IMfile	The physical path to some directory where stescodes.im file need to be saved. The IMfile save the information about the updates, so if this file location is passed as 4th parameter then this file location should be passed on "grabcontacts" function as additional parameter. The directory should be provided with write permission. If IMfile path is provided then the path to bin folder should be provided. eg: D:\myproject\somepath (no slash after path)	Optional

AddressBook Importer

The next step after integrating autoupdate is the AddressBook Importer integration.

Reference

Add reference to StesCodes_OAuth.dll from your project bin folder
- Import the namespace "OAuth"
- Import the namespace "stescodes"
- Import the namespace "WindowsLive"

Function

To start grabbing contacts, the function "RetriveContacts" should be called along with certain parameters as below.

Parameters

Google

Parameters	Description	Required?
1. Token	Authenticated token received from google using OAuth.	Yes
2. Context	Gets the System.Web.HttpContext object associated with the page	Yes
3. IMfile	If you provide the IMfile path as additional parameter to autoupdate function, then you have to provide the same path here as well. eg: D:\myproject\somepath (no slash after path)	Optional

Yahoo

Parameters	Description	Required?
1. oauth_token	Authenticated token received from yahoo using OAuth.	Yes
2. OauthYahooGuid	Guid received from yahoo using OAuth.	Yes
3. tokensecret	Authenticated token secret received from yahoo using OAuth.	Yes
4. Context	Gets the System.Web.HttpContext object associated with the page	Yes
5. IMfile	If you provide the IMfile path as additional parameter to autoupdate function, then you have to provide the same path here as well. eg: D:\myproject\somepath (no slash after path)	Optional

Windows Live

Parameters	Description	Required?
1. LOC	LOC received from Windows Live.	Yes
2. deltok	Authenticated token received from Windows Live using OAuth.	Yes
3. Context	Gets the System.Web.HttpContext object associated with the page	Yes
4. IMfile	If you provide the IMfile path as additional parameter to autoupdate function, then you have to provide the same path here as well. eg: D:\myproject\somepath (no slash after path)	Optional

Outlook and CSV

Parameters	Description	Required?
1. strCSV	CSV content.	Yes
2. type	type of csv file.	Yes
3. Context	Gets the System.Web.HttpContext object associated with the page	Yes
4. IMfile	If you provide the IMfile path as additional parameter to autoupdate function, then you have to provide the same path here as well. eg: D:\myproject\somepath (no slash after path)	Optional

Return Type

The return type is a list collection of class which has the members of two types:-

List<addresslists>

name
email
address
phone

Binding

Once the contacts are grabbed and received in collection object, you should loop through to access the contacts. Binding the data to front end is all customizable.

Error Handling

There are few error messages you need to taken care on your end

Error Message

Error	Description
1. Invalid domain	The license(Signature Key) is not registered for this domain. You shall change/edit your domain here http://stescodes.com/sourceupdate.aspx
2. Invalid key	The Signature Key is invalid.
3. File missing! add code to check update	Please include the code for autoupdate.
4. Add code to check update	Please include the code for autoupdate.
5. Invalid username & password	The username or password is invalid.
6. Please try again	Please try again one more time.
7. Please login to http://www.gmail.com and then try again	If the user account is not used for long time Gmail will ask for CAPTCHA authentication, so user have to login to his account and then try importing.
8. Missing input	Missing the input parameter
9. This service not available on your plan	The service you are requesting to grab contacts are not available on your purchased plan.

Configurations

Fill with your keys for the below in your web.config file

            
       <!-- Configuring Google API-->
       <add key="GoogleApiKey" value="your google API key"/>
       <add key="GoogleSecretKey" value="your google secret key"/>
       
       <!-- Configuring Yahoo API-->
       <add key="consumerKey_yahoo" value="your yahoo API key"/>
       <add key="consumerSecret_yahoo" value="your yahoo secret key"/>
       
       <!-- Configuring Windows Live API-->
       <add key="wll_appid" value="your windows live app id"/>
       <add key="wll_secret" value="your windows live screet key"/>
       <add key="wll_securityalgorithm" value="wsignin1.0"/>
       <add key="wll_returnurl" value="your return url(eg:http://stesbox.com/devenv/liveoauth.aspx)"/>
       <add key="wll_policyurl" value="your policy url(eg: http://stesbox.com/devenv/policy.html)"/>

Inorder to perform the autoupdate process successfully, your project should be read/write enabled. Once found update two files will be updated, one is StesCodes_OAuth.dll inside bin folder and other is stescodes.im which is outside the bin folder. The stescodes.im file has the details of update info.

If you don't want to provide write permission for the entire project, then follow the below steps:

Create a folder with write permission or specify a folder with write permission for IMfile
Pass the location of folder to "checkforupdate" function as fourth parameter(eg: checkforupdate(this.Context, signature,bin location,IMfile location);)
Also specify the path as additional parameter to "RetriveContacts" function

Permissions

Inorder to perform the autoupdate process successfully, your project should be read/write enabled

Turn On/Off AutoUpdate

Turn OFF:

In order to turn off autoupdate, login to http://stescodes.com/sourceupdate.aspx then click OFF button. Once autoupdate is set OFF, the DLL with latest updates will not be updated on your server automatically, you have to manually update by downloading the latest DLL from customer login. No need to providing write permission for bin folder.

Even though you turn OFF the autoupdate feature, you should have the below on your project.

Either you should create a folder with write permission OR provide write permission to root folder. This process is necessary for the stescodes.im file to be created which keeps track of the service validations.
If you create a folder with write permission then specify that location as parameter for "autoupdate" function and "grabContacts" function(refer above for passing parameter).

Turn ON:

In order to turn ON autoupdate, login to http://stescodes.com/sourceupdate.aspx then click ON button. Once autoupdate is set ON, the DLL with latest updates will be updated on your server automatically.

If you turn ON the autoupdate feature, you should have the below on your project

Either you should create a folder with write permission OR provide write permission to root folder.
If you create a folder with write permission then specify that location as parameter for "autoupdate" function and "grabContacts" function(refer above for passing parameter).

Change Domain

If you get the domain is invalid and you purchased license for that domain, then you shall follow the below steps to update your domain.

Edit/Change Domain

To edit or change your domain

Login to http://stescodes.com/sourceupdate.aspx
You shall login using email and password which you received in email during purchase or you shall use the StesCodes transaction id
Once you login, click the edit link near website
Enter the domain details
Click "proceed" to save.