《函数参考::SdkLogin》

<?php


/**
 * 提供登陆验证常用方法及约束登录验证实现
 *
 * @author anysdk
 * @abstract
 * @access public
 */
 abstract class SdkLogin {

    /**
     * HTTP请求库对象
     * 
     * 可用方法 => 调用示例:
     *      
     *      setConnectTimeOut($time = 30) => $this->getHttp()->setConnectTimeOut(10);
     *      setTimeOut($time = 30)        => $this->getHttp()->setTimeOut(10);
     *      getUrl()                      => $this->getHttp()->getUrl();
     *      getCurlError()                => $this->getHttp()->getCurlError();
     *      getHttpCode()                 => $this->getHttp()->getHttpCode();
     *      post_header($url, $data = array(),$header = array()) => $this->getHttp()->post_header($url, $data,$header);
     *      get_header($url, $data = array(),$header = array())  => $this->getHttp()->get_header($url, $data,$header);
     *      post($url, $data = array())                          => $this->getHttp()->post($url, $data);
     *      get($url, $data = array())                           => $this->getHttp()->get($url, $data);
     * 
     * @final
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @return \HttpHelper
     */
    final protected function getHttp() {
    }

    /**
     * 获取SDK所有参数
     * 
     * 相关方法:
     * 
     *      获取所有参数 => $this->setSdkParams($params);
     *      获取指定参数 => $this->getSdkParameter($parameterName);
     * 
     * @final
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @return array
     */
    final protected function getSdkParams() {
    }

    /**
     * 获取打包工具配置sdk参数
     * 
     * 相关方法:
     * 
     *      初始化SDK参数 => $this->setSdkParams($params);
     *      获取所有参数  => $this->getSdkParams();
     * 
     * $this->_sdkParams的数据结构:
     *      stdClass Object
     *       (
     *               [PID]          => 103889
     *               [PKEY]         => 383dbc5d4084ea056f7e29f20b5f0aa9
     *               [Version]      => 0.72
     *               [callback]     => http://dj.qudao.info/anysdk_gov_ne/api/payment/callback
     *               [introduction] => 0
     *       )
     * 
     * @final
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @return Mixed 制定的key存在则返回value,不存在则返回null
     */
    final protected function getSdkParameter($key) {
    }

    /**
     * set user sdk id (sdk name)
     * eg. 360 gfan coco
     * 
     * @final
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @param  String $tag SDK英文标识
     * @return void
     */
    final protected function setSdkName($tag) {
    }

    /**
     * get user sdk id (sdk name)
     * eg. 360 gfan coco
     * 
     * @final
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @return String SDK英文标识
     */
    final protected function getSdkName() {
    }

    /**
     * 初始化自定义错误信息
     * 
     * @final
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @param  Array $errors error_key => error_value形式的错误信息数组
     * @return void
     */
    final protected function setCustomErrors($errors) {
    }

    /**
     * 获取所有自定义的错误信息
     * 
     * @final
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @return Array 所有自定义的错误信息数组,error_key => error_value形式
     */
    final protected function getCustomErrors() {
    }

    /**
     * 获取所有错误信息,包括AnySDK官方的和插件自定义的
     * 
     * @final
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @return array
     */
    final protected function getErrors() {
    }

    /**
     * 设置渠道用户唯一标识(uid)
     * 
     * 相关方法:
     * 
     *      设置用户UID => $this->toSetUserId($userId);
     *      记录用户UID => $this->logSdkUserId($userId);
     * 
     * @final
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @param  String $userId user id from channel server
     * @return void
     */
    final protected function setUserId($userId = '') {
    }

    /**
     * 获取渠道用户唯一标识(uid)
     * 
     * 相关方法:
     *      
     *      设置用户UID => $this->setUserId($userId);
     *      设置用户UID => $this->toSetUserId($userId);
     * 
     * @final
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @return String 渠道用户唯一标识(uid)
     */
    final protected function getUserId() {
    }

    /**
     * 获取AnySDK官方6位渠道号:如000000
     * 
     * @final
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @return String AnySDK官方6位渠道号:如000000
     */
    final protected function getChannelId() {
    }

    /**
     * 获取HTTP请求参数,包括GET&&POST,如果请求参数是以raw方式发送的,请在插件内自行使用php://input获取
     * 
     * @final
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @return array
     */
    final protected function getParams() {
    }

    /**
     * 获取插件ID
     * 
     * @final
     * @access protected
     * @date   2015-09-25
     * @author 苏晓超<xiaochao.su@chukong-inc.com>
     * @return Int AnySDK官方插件ID
     */
    final protected function getPluginId(){
    }

    /**
     * 在日志中记录登录验证时间
     * 
     * @final
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @return void
     */
    final protected function logLoginTime() {
    }

    /**
     * 在日志中记录HTTP请求参数
     * 
     * @final
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @param  array $params request params (array('a'=>1,'b'=>2))
     */
    final protected function logRequestParams($params) {
    }

    /**
     * 在日志中记录当前登录验证请求的App信息
     * 
     * @final
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @param array $app app info (array('app_id'=>1,'channel_id'=>2,....))
     */
    final protected function logAppInfo($app = array()) {
    }

    /**
     * 在日志中记录向渠道服务器发起的HTTP请求参数
     * 
     * @final
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @param  String $url url(http://xxx.xxx?a=1&b=2)
     * @param  mixed $params params (array('a'=>1,'b'=>2)) || a=1&b=2
     */
    final protected function logSdkCheckUrl($url, $params = null) {
    }

    /**
     * 在日志中记录渠道服务器的HTTP响应消息
     * 
     * @final
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @param  mixed $data  string that sdk server response
     * @return void
     */
    final protected function logSdkCheckReturn($data = '') {
    }

    /**
     * 在日志中记录渠道用户唯一标识(uid)
     * 
     * @final
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * 
     * @param string $userId userId=123456789
     */
    final protected function logSdkUserId($userId = '') {
    }

    /**
     * 在日志中记录渠道用户名,这是可选的,并不是每个渠道都会返回用户名
     * 
     * @final
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @param string $userName userName=abcdefg
     */
    final protected function logSdkUserName($userName = '') {
    }

    /**
     * 在日志中记录返回给游服的消息
     * 
     * 相关方法:
     * 
     *      登录验证逻辑           => $this->toCheckLogin($params);
     *      记录发给渠道服务器的消息 => $this->logSdkCheckUrl($url);
     * 
     * @access protected
     * @final
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @param  String $return json格式的响应消息
     */
    final protected function logAnySDKReturn($return) {
    }

    /**
     * 检查指定的参数是否有传递或传递的值是否为空。此方法在参数检查失败之后会终止插件的运行
     * 
     * @access protected
     * @final
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @param  Array $params array('a'=>1,'c'=>'0') 被检测数组
     * @param  Array $keys array('a','b') 检测的key
     * @param  Array $compatibleKeys array('ext1'=>'a','ext2'=>'b') 用于检查$keys的别名是否存在
     * @param  Boolean $toCheckEmpty to check empty
     * @return Boolean
     */
    final protected function checkParams($params, $keys, $compatibleKeys, $toCheckEmpty = false) {
    }

    /**
     * 通过appid初始化app,一般用在异步通知接口中
     * 
     * @access protected
     * @final
     * @date   2015-12-23
     * @author 李播<libo@anysdk.com>
     * @param  Int $appId
     */
    final protected function initApp ($appId) {
    }

    /**
     * 检查App。此方法在失败的情况下会终止插件的运行。
     * 
     * @access protected
     * @final
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @return boolean (if success return TRUE, else wiil echo error message and exit)
     */
    public function checkApp() {
    }

    /**
     * 获取url之后通过/分割后的参数
     * 
     * @access protected
     * @final
     * @date   2015-12-23
     * @author 李播<libo@anysdk.com>
     * @return Array
     */
    final protected function getUrlExplodeParams() {
    }

    /**
     * 登录验证api错误返回
     * 
     * 相关方法:
     *      
     *      获取错误消息           => $this->getErrorCode($error);
     *      发送登录验证结果消息    => $this->returnResponse($return);
     * 
     * @access protected
     * @final
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @param  String $error error tag
     * @param  Array  $more  array('ext'=>array(...),'common'=>array(...))
     */
    final protected function responseError($error, $more = null) {
    }

    /**
     * 登陆验证api成功返回
     * 
     * 相关方法:
     *      
     *      发送登录验证结果消息    => $this->returnResponse($return);
     *      获取登录验证结果通用消息 => $this->getReturnCommonData();
     * 
     * @access protected
     * @final
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @param  Mixed $data
     * @param  Array $more array('ext2'=>array(...),'common2'=>array(...))
     */
    final protected function responseSuccess($data, $more = null) {
    }

    /**
     * 将登录验证结果发送给游服。此方法会终止插件的运行。
     * 
     * 相关方法:
     * 
     *      发送登录验证失败消息 => $this->responseSuccess($data, $more = null);
     *      发送登录验证成功消息 => $this->responseError($error, $more = null);
     *      记录日志           => $this->logAnySDKReturn($responseMessage . $noticeError);
     * 
     * @link http://docs.anysdk.com/OauthLogin#AnySDK.E7.99.BB.E5.BD.95.E9.AA.8C.E8.AF.81.E5.93.8D.E5.BA.94.E6.95.B0.E6.8D.AE AnySDK登录验证响应数据
     * @access protected
     * @final
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @param  Array $return 返回的数据
     * @return String
     */
    final public function returnResponse($return) {
    }

    /**
     * 设置被动通知接口的响应消息,包括成功响应消息和失败响应消息
     * 
     * @final
     * @access protected
     * @date   2015-12-23
     * @author 李播<libo@anysdk.com>
     * @param  String $success 成功响应消息
     * @param  mixed $failure  失败响应消息
     */
    final protected function setReturn($success = '', $failure = '') {
    }

    /**
     * 获取要返回给渠道(其他请求方)的成功响应信息
     * 
     * 相关方法:
     * 
     *      $this->noticeResponse($responseMessage = '', $noticeError = '');
     * 
     * @final
     * @access protected
     * @date   2015-12-23
     * @author 李播<libo@anysdk.com>
     * @return String 要返回给渠道的成功响应消息
     */
    final protected function getSuccessReturn() {
    }

    /**
     * 获取要返回给渠道(其他请求方)的失败响应信息
     * 
     * 相关方法:
     * 
     *      $this->noticeResponse($responseMessage = '', $noticeError = '');
     * 
     * @final
     * @access protected
     * @date   2015-12-23
     * @author 李播<libo@anysdk.com>
     * @return String 要返回给渠道的失败响应消息
     */
    final protected function getFailureReturn() {
    }

    /**
     * AnySDK发送响应消息给渠道服务器(其他请求方)。此方法会终止插件的运行
     * 
     * 在被动通知接口中,我们一般需要返回特定的信息给渠道服务器(或其他请求发起方)
     * 响应消息一般分为:成功响应消息、失败响应消息
     * 发送的响应消息会被记录在Dev后台的登陆日志列表中
     * 
     * 相关方法:
     *      
     *      获取成功响应消息 => $this->getFailureReturn();
     *      获取失败响应消息 => $this->getSuccessReturn();
     *      记录日志        => $this->logAnySDKReturn($responseMessage . $noticeError);
     * 
     * @final
     * @access protected
     * @date   2015-12-23
     * @author 李播<libo@anysdk.com>
     * @param  String $responseMessage  成功响应信息|失败响应信息
     * @param  String $noticeError      错误信息
     */
    final protected function noticeResponse($responseMessage = '', $noticeError = '') {
    }

    /**
     * 初始化官方配置的错误信息和错误代码
     * 
     * @access protected
     * @final
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @return Array 官方错误信息和错误代码数组
     */
    final protected function initOfficalErrors() {
    }

    /**
     * key => value存储工具
     * 
     * 可用的方法以及调用实例:
     * 
     *     get($name)                       => $this->getStorage($namespace)->get($name);
     *     set($name, $value, $ttl = 0)     => $this->getStorage($namespace)->set($name, $value);
     *     del($name)                       => $this->getStorage($namespace)->del($name);
     * 
     * @access protected
     * @final
     * @date   2015-12-23
     * @author 李播<libo@anysdk.com>
     * @param  String $namespace (默认值:default) hash一级key的后缀
     * @return \PluginKVStorage 对象
     */
    final protected function getStorage ($namespace = 'default') {
    }

    /**
     * 初始化插件运行环境 
     * 
     * 相关方法:
     * 
     *      $this->logRequestParams($params);
     *      $this->setSdkName($sdkname);
     *      $this->toSetCustomErrors();
     * 
     * @abstract
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @param  Array $params HTTP GET&&POST请求参数,请求方以raw方式发送的参数请自行用php://input获取
     * @return void
     */
    abstract protected function init($params);

    /**
     * 检查请求参数是否足够
     * 
     * 相关方法:
     * 
     *      检查参数 => $this->checkParams($params, $keys, $compatibleKeys, true);
     * 
     * 参考实现:
     * public function toCheckParams($params) {
     *       // $compatibleKeys用于指定$keys元素的别名,例如playId的别名是ext1
     *       $keys = array('playId', 'isGuest', 'token');
     *       $compatibleKeys = array('playId' => 'ext1', 'isGuest' => 'ext2', 'token' => 'ext3');
     *       $this->checkParams($params, $keys, $compatibleKeys);
     * }
     * 
     * @abstract
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @param Array $params HTTP GET&&POST请求参数,请求方以raw方式发送的参数请自行用php://input获取
     * @return void
     */
    abstract protected function toCheckParams($params);

    /**
     * 检查App,此方法是对相关方法的封装,以便特定情况下的定制
     * 
     * 相关方法:
     * 
     *      检查App => $this->checkApp();
     * 
     * @abstract
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @param  Array $params HTTP GET&&POST请求参数,请求方以raw方式发送的参数请自行用php://input获取
     * @return void
     */
    abstract protected function toCheckApp();

    /**
     * 登录验证主要处理逻辑
     * 
     * 一般模式:
     * 
     *      1、通过 $this->getSdkParameter('xxx') 获取渠道方参数
     *      2、组装并发起HTTP请求,去渠道方服务器验证token,sessionid等用户登录验证数据
     *      3、记录向渠道方发起HTTP请求的时候的相关信息,如url,请求参数,渠道方响应结果等
     *      4、解析、验证渠道方返回参数,并根据结果返回相应正确的内容给游服
     * 
     * 上面列出来的步骤是一般情况下的处理流程,某些特殊渠道可能会不一样,具体以渠道SDK文档给出的逻辑为准
     * 
     * @abstract
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @param  Array $params HTTP GET&&POST请求参数,请求方以raw方式发送的参数请自行用php://input获取
     * @return void
     */
    abstract protected function toCheckLogin($params);

    /**
     * 以 error_key => error_value 的形式自定义错误信息和错误代码。
     * 请尽量将自定义错误信息定义的详细,意义清晰。
     * 
     * 参考实现:
     * public function toSetCustomErrors() {
     *      $errors = array(
     *              'jinli_login_error_1007'    => '未知错误,solution:提供相应的 r 和 wid 值供Amigo 服务端分析',
     *              'jinli_login_error_1009'    => 'HTTP 格式错误,必须提供 Authorization 认证头',
     *              'jinli_login_error_1010'    => '信令格式错误',
     *              'jinli_login_error_1011'    => '认证失败',
     *              'jinli_login_error_1020'    => '服务器内部错误,请提供 r 和 wid 参数给Amigo 服务端分析',
     *              'jinli_login_error_1031'    => '发送超时,请提供 r 和 wid 参数给Amigo 服务端分析',
     *              'jinli_login_error_1050'    => 'MAC签名的timestamp 已过期',
     *              'jinli_login_error_1051'    => 'MAC签名的nonce重复,nonce参数不能重复,请使用随机数',
     *              'jinli_login_error_unknown' => '未知的错误码',
     *      );
     *      $this->setCustomErrors($errors);
     * }
     * 
     * 相关方法:
     * 
     *      定义 => $this->setCustomErrors($errors);
     *      获取 => $this->responseError($key);
     * 
     * @abstract
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @return void
     */
    abstract protected function toSetCustomErrors();

    /**
     * 自定义设置用户唯一标识(uid),此方法是对相关方法的重新封装,以便特定情况下的定制
     * 
     * 相关方法:
     * 
     *      设置渠道用户ID => $this->setUserId($userId);
     * 
     * @abstract
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @param  String $userId 渠道用户ID,此传入参数会被用于返回给游服,在Dev后台记录日录日志
     * @return void
     */
    abstract protected function toSetUserId($userId);

    /**
     * 登录验证接口主入口方法
     * 
     * 相关方法:
     * 
     *      初始化插件   => $this->init();
     *      检查请求参数  => $this->toCheckParams($params);
     *      检查App     => $this->toCheckApp();
     *      登录验证逻辑  => $this->toCheckLogin($params);
     * 
     * @abstract
     * @access protected
     * @date   2015-01-29
     * @author 陈清基<qingji.chen@chukong-inc.com>
     * @author 李播<libo@anysdk.com>
     * @param  Array $params HTTP GET&&POST请求参数,请求方以raw方式发送的参数请自行用php://input获取
     * @return void
     */
    abstract protected function check($params);

 }