HVKAPI 1.1 README FILE
================================================================================



DESCRIPTION
--------------------------------------------------------------------------------

HVKAPI is the module for using VK.COM API in Perl language,
which don't support (by default necessary) visual components. To use it you
don't need any experience in web technologies or something similar. All you need 
to do is to create an object, log in and make requests.

Since version 0.3 HVKAPI supports browser-like HTTP requests (through 
LWP::UserAgent object) besides dealing with API directly. Captcha handling is 
also available in these requests, but keep in mind that VK can change it's 
layout (as well as a login algorythm) at any moment. It can break down login 
function or "captcha-catch" methods.

REQUIREMENTS
--------------------------------------------------------------------------------
First of all, LWP is required. Additionally you may need to install 
LWP::Protocol::https module, otherwise all this crap will not work. 

Also you'll need Net::INET6Glue::INET_is_INET6 and Net::SSLGlue::LWP
for IPv6 supporting. If you don't need IPv6, just comment these modules in 
HVKAPI.pm

METHODS 
--------------------------------------------------------------------------------


HVKAPI defines only one class called HVKAPI, which provides the following 
methods: 

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
new (captchaCallback,appid, useragent)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Class constructor. 
 - appid (int)- id of your desktop application (you must create it at first). 
                if omitted, default id will be used. 
 - UserAgent (string)- obvious. if omitted, default value will be used. 
 - captchaCallback (pointer) - callback-function to deal with captcha. 
 
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
setCallback (callbackFunc)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Changes a captcha-callback function to callbackFunc. Your callback receives an
associative array (in PHP) or a hash (in Perl) with these fields:
	difficult - so called difficulty (field "s" in the address)
	captcha_sid - captcha sid 
	captcha_url - captcha image link, for example, 
			http://vkontakte.ru/captcha.php?sid=1234567890&s=0
Callback function should return a string - captcha answer. 

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
login (email, pass, mphone)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Login function, parameters are quite obvious. mphone should be the last 4 numbers 
of mobile phone - in case of security check. Function returns a hash (in Perl)
or associative array (in PHP) with these keys: 
	errcode - error code
	errdesc - error description
If succeed, errcode = 0. Possible error codes are: 
	101  - incorrect login data
	103  - security check (or mphone is undefined or invalid)
	666  - the captcha appeared
	      (and you haven't set callback)


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
request (method, params)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
API request itself. 
 - method (string) - method's name (check userapi.com)
 - params - hash or associative array (in Perl/PHP), contains parameters of the
            method.

Returns a hash or an associative array (in Perl/PHP). Look userapi.com for
details.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
interface([browser])
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
LWP::UserAgent object for HTTP requests. Note that if you're using restoreSession
(not ordinary login), there will be no cookies for http-requests, e.g. without API.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
postWithCaptcha(...)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Just a POST-request through the LWP::UserAgent object with captcha processing. 

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
restoreSession(access_token, mid)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Restores user session using mid and access_token "session variables". 


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
getSessionVars()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Returns a hash with session variables (mid, access_token), which identify user
session. With "restoreSession" this function may be used for 
saving/restoring cookies.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
get(), post()
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These methods are abstract and just call proper ones of LWP::UserAgent


CONSTANTS AND DEFAULT VALUES
--------------------------------------------------------------------------------
Located at the beginning of the module and well-documented. You can change
a default application id, UserAgent and something else. Or break everything down,
yep.