swc-api/swcapiInterface.inc at master · OlwinFroon/swc-api · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
<?php //////////////////////////////////////////////////////////////////////////
// custom/api/swcapiInterface.inc: Technical layer for the SWC API
// TFMS (c) 2016 Olwin Froon, Trade Federation
////////////////////////////////////////////////////////////////////////////////
// of 160717: refreshAccessToken
// of 160716: revokeAccess
// of 160715: initial spin-off
////////////////////////////////////////////////////////////////////////////////


interface swcapiInterface {

  public static function getError($clear);
    // Returns a string consisting of error code and text, which describes the nature
    // of the recent error, an empty string if nothing went wrong.
    //
    // $clear (optional): TRUE will reset the error marker afterwards.
    // If omitted, $clear defaults to FALSE.


  public static function getErrorCode();
    // Returns a numerical error code if something went wrong, a zero otherwise.


  public static function getErrorText($clear);
    // Returns the text message part of the recent error,
    // an empty string if nothing went wrong.
    //
    // $clear (optional): TRUE will reset the error marker afterwards.
    // If omitted, $clear defaults to FALSE.


  public static function hasError();
    // Returns TRUE if the recent API operation caused an error.


  public static function authorize(array $permissions, $state, $accessmode);
    // Tries to authorize a set of API permissions for the currently logged-in character.
    // Returns TRUE if the attempt was successful, FALSE otherwise.
    //
    // $permissions (string array): the API permissions ('character_read',
    // 'character_stats', ...) your application wishes to be granted by the user.
    // An empty array will cause the API to clear all current permissions on SWC's
    // side.
    //
    // $state (optional): a marker to recognize which part of your application sent
    // this request.
    // If omitted, $state defaults to 'auth'.
    //
    // $accessmode (optional):
    // - 'online' = one time permission, expires with the access token
    // - 'offline' = permission will persist, access token can be refreshed
    // If omitted, $accessmode defaults to 'offline'.
    //
    // CAVEAT: currently, the $permissions array can't be empty. If you wish to
    // disable API access for your user, request a single pointless permission
    // (e.g. 'character_stats' which wouldn't work without 'character_read').


	public static function refreshAccessToken($refreshtoken);
    // Tries to refresh an access token when it's expired.
    // Returns an array with access token, refresh token, scope and unix expiration
    // timestamp if everything went well, FALSE otherwise.
    //
    // $refreshtoken: current valid refreshtoken


  public static function requestAccessToken($authcode, $accessmode);
    // Tries to request an access token after successful authorization.
    // Returns an array with access token, refresh token, scope and unix expiration
    // timestamp if everything went well, FALSE otherwise.
    //
    // $authcode: what was sent as "code" via the SWC consent screen
    //
    // $accessmode:
    // - 'online' = one time permission, expires with the access token
    // - 'offline' = permission will persist, access token can be refreshed
    // If omitted, accessmode defaults to 'offline'.


  public static function revokeAccess($refreshtoken);
    // Tries to revoke the current access token.
    // Returns TRUE if everything went well, FALSE otherwise.
    //
    // $refreshtoken: the user's current refresh token.
    //
    // Obviously, this won't work in online access mode, since there won't be a refresh
    // token.
    //
    // CAVEAT: currently, this will remove ALL access tokens for your application,
    // not just the one for the single user owning that refresh token.
    // After next sync, this will most probably work properly.

}