Why do we call it vdata?
TOP
Truth be told, V is a pretty girl's name. Uh huh, so, we hope vdata would be pretty too for you.
 
What does vdata look like?
TOP
vdata is JSON-based protocol, when you call a HTTP service played by vdata protocol, you will see the response from server:
{
    "name"          : "",       //  string, name of service
    "url"           : "",       //  string, address of service
    "version"       : "1.0",    //  string, version of service
    "errorid"       : 0,        //  numeric,    error id
    "errordesc"     : "",       //  string, desciption of error
    "vdata"         : {}        //  user customized data.
                                //      it might be an array or an object with
                                //      contents of a string, number, array or object.
}
        
 
Call services at client
TOP
Get request in PHP
use dekuan\vdata\CConst;
use dekuan\vdata\CRequest;


$cRequest   = CRequest::GetInstance();
$arrResp    = [];
$nCall      = $cRequest->Get
(
    [
        'url'       => 'http://api-account.dekuan.org/user/info',
        'data'      => [],
        'version'   => '1.0',   //  required version of service
        'timeout'   => 30,      //  timeout in seconds
        'cookie'    => [],      //  array or string are both okay.
    ],
    $arrResp
);
if ( CConst::ERROR_SUCCESS == $nCall &&
    $cRequest->IsValidVData( $arrResp ) )
{
    //  arrResp
    //      'errorid'   : error id
    //      'errordesc' : error desc
    //      'vdata'     : virtual data
    //      'version'   : in-service version of service
    //      'json'      : original json array
    print_r( $arrResp );
}
        
Post request in PHP
use dekuan\vdata\CConst;
use dekuan\vdata\CRequest;


$cRequest   = CRequest::GetInstance();
$arrResp    = [];
$nCall      = $cRequest->Post
(
    [
        'url'       => 'http://api-account.dekuan.org/login',
        'data'      =>
        [
            'u_name'    => 'username',
            'u_pwd'     => 'password',
            'u_keep'    => 1
        ],
        'version'   => '1.0',   //  required version of service
        'timeout'   => 30,      //  timeout in seconds
        'cookie'    => [],      //  array or string are both okay.
    ],
    $arrResp
);
if ( CConst::ERROR_SUCCESS == $nCall &&
    $cRequest->IsValidVData( $arrResp ) )
{
    //  arrResp
    //      'errorid'   : error id
    //      'errordesc' : error desc
    //      'vdata'     : virtual data
    //      'version'   : in-service version of service
    //      'json'      : original json array
    print_r( $arrResp );
}
        
Raw HTTP contents request in PHP
It means we send a HTTP request and receive the row contents.
use dekuan\vdata\CConst;
use dekuan\vdata\CRequest;


$cRequest   = CRequest::GetInstance();
$arrRaw     = [];
$nCall      = $cRequest->HttpRaw
(
    [
        'method'    => 'POST',       //  GET, POST
        'url'       => 'http://api-account.dekuan.org/login',
        'data'      =>
        [
            'u_name'    => 'username',
            'u_pwd'     => 'password',
            'u_keep'    => 1
        ],
        'version'   => '1.0',   //  required version of service
        'timeout'   => 30,      //  timeout in seconds
        'cookie'    => [],      //  array or string are both okay.
    ],
    $arrRaw
);
if ( CConst::ERROR_SUCCESS == $nCall &&
    $cRequest->IsValidRawResponse( $arrRaw ) )
{
    //  $arrRaw
    //      'data'      : HTTP body/contents
    //      'status'    : HTTP status code
    //      'headers'   : responded headers
    print_r( $arrRaw );
}
        
Get request in JS/jQuery
<script src="components/jquery/dist/jquery.js" ladep="1"></script>
<script src="components/vdata/dist/js/jquery/vdata.js" ladep="1"></script>
<script>
VDATA.Get
(
    {
        'url'	    : 'http://api-account.dekuan.org/user/info',
        'version'   : '1.0',    //  required service version
        'timeout'   : 3000,     //  timeout in milliseconds
        'async'     : true,     //  asynchronous? default is true
        'data'	    : {}
    },
    function( oJsonData )
    {
        if ( VDATA.ERROR.SUCCESS == oJsonData['errorid'] )
        {
            //  successfully
        }
        else if ( VDATA.ERROR.NETWORK == oJsonData['errorid'] )
        {
            //	network
        }
        else if ( VDATA.ERROR.EXCEPTION == oJsonData['errorid'] )
        {
            //	exception
        }
        else
        {
            //  some cases else
        }
    }
);
</script>
        
Post request in JS/jQuery
<script src="components/jquery/dist/jquery.js" ladep="1"></script>
<script src="components/vdata/dist/js/jquery/vdata.js" ladep="1"></script>
<script>
VDATA.Post
(
    {
        'url'	    : 'http://api-account.dekuan.org/login',
        'version'   : '1.0',    //  required service version
        'timeout'   : 3000,     //  timeout in milliseconds
        'async'     : true,     //  asynchronous? default is true
        'data'	    :
        {
            'u_name'    : 'username',
            'u_pwd'     : 'password',
            'u_keep'    : 1
        }
    },
    function( oJsonData )
    {
        if ( VDATA.ERROR.SUCCESS == oJsonData['errorid'] )
        {
            //  successfully
        }
        else if ( VDATA.ERROR.NETWORK == oJsonData['errorid'] )
        {
            //	network
        }
        else if ( VDATA.ERROR.EXCEPTION == oJsonData['errorid'] )
        {
            //	exception
        }
        else
        {
            //  some cases else
        }
    }
);
</script>
        
 
 
Get request in JS/Angular
<script src="components/angular/angular.js" ladep="1"></script>
<script src="components/vdata/dist/js/angular/ng-vdata.js" ladep="1"></script>
<script>
angular.module
(
    'networkApp', []
)
.controller
(
    "vdataTestController",
    [
        "$scope", "vdataConst", "vdataFactory",
        function ( $scope, vdataConst, vdataFactory )
{
    $scope.PostLoginRequest = function()
    {
        vdataFactory.Get
        (
            {
                'url'       : 'http://api-account.dekuan.org/user/info',
                'version'   : '1.0',    //  required service version
                'timeout'   : 3000,     //  timeout in milliseconds
                'async'     : false,    //  asynchronous? default is true
                'data'	    : {}
            },
            function( oJsonData )
            {
                if ( vdataConst.ERROR.SUCCESS == oJsonData['errorid'] )
                {
                    //  successfully
                }
                else if ( vdataConst.ERROR.NETWORK == oJsonData['errorid'] )
                {
                    //	network
                }
                else if ( vdataConst.ERROR.EXCEPTION == oJsonData['errorid'] )
                {
                    //	exception
                }
                else
                {
                    //  some cases else
                }
            }
        );
    };
});
</script>
        
Post request in JS/Angular
<script src="components/angular/angular.js" ladep="1"></script>
<script src="components/vdata/dist/js/angular/ng-vdata.js" ladep="1"></script>
<script>
angular.module
(
    'networkApp', []
)
.controller
(
    "vdataTestController",
    [
        "$scope", "vdataConst", "vdataFactory",
        function ( $scope, vdataConst, vdataFactory )
{
    $scope.PostLoginRequest = function()
    {
        vdataFactory.Post
        (
            {
                'url'       : 'http://api-account.dekuan.org/login',
                'version'   : '1.0',    //  required service version
                'timeout'   : 3000,     //  timeout in milliseconds
                'async'     : false,    //  asynchronous? default is true
                'data'	    :
                {
                    'u_name'    : 'username',
                    'u_pwd'     : 'password',
                    'u_keep'    : 1
                }
            },
            function( oJsonData )
            {
                if ( vdataConst.ERROR.SUCCESS == oJsonData['errorid'] )
                {
                    //  successfully
                }
                else if ( vdataConst.ERROR.NETWORK == oJsonData['errorid'] )
                {
                    //	network
                }
                else if ( vdataConst.ERROR.EXCEPTION == oJsonData['errorid'] )
                {
                    //	exception
                }
                else
                {
                    //  some cases else
                }
            }
        );
    };
});
</script>
        
 
Respond client at server
TOP
Set name of service
use dekuan\vdata\CResponse;


$cResponse  = CResponse::GetInstance();

$cResponse->SetServiceName( 'vdata protocol service' );
$cResponse->SetServiceUrl( 'http://vdata.dekuan.org/vdata' );
$cResponse->Send
(
    0,                      //  error id
    "error desc",           //  error description
    [ "info" => "..." ],    //  customized info
    '1.0'                   //  in-service version of service
);
        
Set url of service
use dekuan\vdata\CResponse;


$cResponse  = CResponse::GetInstance();

$cResponse->SetServiceName( 'vdata protocol service' );
$cResponse->SetServiceUrl( 'http://vdata.dekuan.org/vdata' );
$cResponse->Send
(
    0,                      //  error id
    "error desc",           //  error description
    [ "info" => "..." ],    //  customized info
    '1.0'                   //  in-service version of service
);
        
Set CORS domains
use dekuan\vdata\CResponse;


$cResponse  = CResponse::GetInstance();

$cResponse->SetServiceName( 'vdata protocol service' );
$cResponse->SetServiceUrl( 'http://vdata.dekuan.org/vdata' );
$cResponse->SetCorsDomains([ 'calling-domain1.com', 'calling-domain2.com' ]);
$cResponse->Send
(
    0,                      //  error id
    "error desc",           //  error description
    [ "info" => "..." ],    //  customized info
    '1.0'                   //  in-service version of service
);
        
Respond client by Response object
The Response object is an instance of Symfony\Component\HttpFoundation\Response
use dekuan\vdata\CResponse;


$cResponse  = CResponse::GetInstance();

$cResponse->SetServiceName( 'vdata protocol service' );
$cResponse->SetServiceUrl( 'http://vdata.dekuan.org/vdata' );
$cResponse->Send
(
    0,                      //  error id
    "error desc",           //  error description
    [ "info" => "..." ],    //  customized info
    '1.0'                   //  in-service version of service
);
        
Respond client by GetVDataArray
use dekuan\vdata\CResponse;


$cResponse  = CResponse::GetInstance();

$cResponse->SetServiceName( 'vdata protocol service' );
$cResponse->SetServiceUrl( 'http://vdata.dekuan.org/vdata' );
$arrJson    = $cResponse->GetVDataArray
(
    0,                      //  error id
    "error desc",           //  error description
    [ "info" => "..." ],    //  customized info
    '1.0'                   //  in-service version of service
);
echo json_encode( $arrJson );
        
Respond client by GetVDataString
use dekuan\vdata\CResponse;


$cResponse  = CResponse::GetInstance();

$cResponse->SetServiceName( 'vdata protocol service' );
$cResponse->SetServiceUrl( 'http://vdata.dekuan.org/vdata' );
$arrJsonStr = $cResponse->GetVDataString
(
    0,                      //  error id
    "error desc",           //  error description
    [ "info" => "..." ],    //  customized info
    '1.0'                   //  in-service version of service
);
echo $arrJsonStr;
        
 
Convenient methods in class CVData
TOP
IsValidVData( $arrJson )
Check if $arrJson is a valid vdata json. About What is a valid vdata, please see What does vdata look like?
IsReservedKey( $sKey )
Check if $sKey is the reserved key of vdata json. For example: 'name', 'url', 'errorid', 'errordesc', 'vdata' and 'parents' are the reserved keys.
GetDefaultVDataJson()
You will receive an array like this:
[
    'errorid'   => intval( CConst::ERROR_UNKNOWN ),
    'errordesc' => '',
    'vdata'     => [],
    'version'   => self::SERVICE_DEFAULT_VERSION
]
        
GetDefaultVersion()
You will always receive a string "1.0".
GetContentTypeWithVersion()
You will always receive a string "application/json; version:1.0".
IsAllowedCorsRequest()
According to the domain of calling client and the settings by SetCorsDomains.
You will receive true if the domain of calling client was set to white list, false otherwise.
 
Convenient methods in class CRequest
TOP
IsValidRawResponse( $arrData )
Check if $arrData is a valid raw data array responded by calling method HttpRaw. An valid row data array like this:
[
    'data'      => '',      //  HTTP body/contents
    'status'    => 200,     //  HTTP status code
    'headers'   => [],      //  responded headers
]
        
 
Convenient methods in class CRemote
TOP
GetAcceptedVersionEx()
You will receive a string of required version from the node Accept of HTTP header sent by client.
For example: "1.0", "1.1" and so on.
 
Convenient methods in class CCors
TOP
GetRefererHost( $bWithScheme = false )
You will receive a string of domain name from the node Referer of HTTP header sent by client. For example: "vdata.dekuan.org".
If you set the parameter $bWithScheme as true, you will receive a string of domain name with scheme. For example: "http://vdata.dekuan.org".
 
Common constants
TOP
Common status
In order to make whole project clearly and easy to develop with each members, We strongly recommend you that use our common state codes for all of HTTP service projects.
status defines status code remark
STATUS_UNKNOWN -1 unknown
STATUS_UNVERIFIED 0 unverified
STATUS_OKAY 1 okay
STATUS_DELETED 2 deleted
STATUS_EXPIRED 3 expired
STATUS_DENIED 4 denied
STATUS_COMPLETE 5 complete
STATUS_ABORT 6 abort
STATUS_PENDING 7 pending
STATUS_ACCEPTED 8 accepted
STATUS_REJECTED 9 rejected
STATUS_ARCHIVED 10 archived
STATUS_LOCKED 11 locked
STATUS_UNLOCKED 12 unlocked
 
Common error codes
We defined the common error codes and the range of user customized error codes.
error defines error code remark
ERROR_SUCCESS 0 successfully
ERROR_UNKNOWN -100000 unknown errors
ERROR_ACCESS_DENIED -100001 access denied
ERROR_PARAMETER -100002 error in parameters
ERROR_PERMISSION -100003 error in permission
ERROR_EXPIRED -100004 error in expired
ERROR_NOT_LOGGEDIN -100005 error in not logged in
ERROR_FAILED_LOGGEDIN -100006 error in failed logged in
ERROR_CREATE_INSTANCE -100010 error in creating instance
ERROR_EXCEPTION -100011 error in exception
ERROR_DB_SELECT -100050 error in selecting database
ERROR_DB_UPDATE -100051 error in updating database
ERROR_DB_INSERT -100052 error in inserting database
ERROR_DB_DELETE -100053 error in deleting database
ERROR_DB_DROP -100054 error in dropping database
ERROR_DB_TRANSACTION -100060 error in transaction
ERROR_DB_TABLE_NAME -100065 error in table name
ERROR_REQUEST_VIA_IP -100100 bad request via ip request
ERROR_MO_NOT_ENOUGH_COINS -100200 not enough coins
ERROR_MO_HIRE_OVERDUE -100201 the hiring date is overdue
ERROR_MO_TRANSACTION_TYPE -100202 error consume type
ERROR_NETWORK -100300 error network
ERROR_JSON -100301 error json
ERROR_JSON_ERRORID -100302 error json.errorid
ERROR_JSON_ERRORDESC -100303 error json.errordesc
ERROR_JSON_VDATA -100304 error json.vdata
 
The range of user customized error codes
If you need define error codes, We strongly recommend you that your error code starts with CConst::ERROR_USER_START and less than CConst::ERROR_USER_END in one project.
error defines error code remark
ERROR_PROJECT_START 1000000 start of project error id
ERROR_PROJECT_END 9900000 end of project error id
ERROR_USER_START 10000 start of user customized error id
ERROR_USER_END 99999 end of user customized error id
 
For example:
<?php

class CConstAccount
{
    //
    //	define a customized error id:
    //

    //	1, define id for this project
    //     project id might be:
    //     1, 2, 3 ... 99
    const ERROR_PROJECT_ID      = 1;

    //	2, define the start number of error id for whole project
    const ERROR_PROJECT_BASE    = CConst::ERROR_PROJECT_START * self::ERROR_PROJECT_ID + CConst::ERROR_USER_START;

    const ERROR_DATA_NOT_EXIST  = CConst::ERROR_PROJECT_BASE + 1;     //	data does not exists
    const ERROR_USER_NOT_EXIST  = CConst::ERROR_PROJECT_BASE + 10;    //	user does not exists
}