Go to the source code of this file.
Namespaces | |
| namespace | Elgg |
Classes | |
| class | GenericResult |
| class | SuccessResult |
| class | ErrorResult |
| class | ElggHMACCache |
Functions | |
| get_call_method () | |
| Get the request method. | |
| get_parameters_for_method ($method) | |
| This function analyses all expected parameters for a given method, returning them in an associated array from input. | |
| obtain_user_token ($username, $password) | |
| Obtain a token for a user. | |
| validate_user_token ($site, $token) | |
| Validate a token against a given site. | |
| expose_function ($method, $function, array $parameters=NULL, $description="", $call_method="GET", $require_auth_token=true, $anonymous=false) | |
| Expose an arbitrary function as an api call. | |
| execute_method ($method, array $parameters, $token="") | |
| Executes a method. | |
| list_all_apis () | |
| Simple api to return a list of all api's installed on the system. | |
| auth_gettoken ($username, $password) | |
| The auth.gettoken API. | |
| map_api_hash ($algo) | |
| Map various algorithms to their PHP equivs. | |
| calculate_hmac ($algo, $time, $api_key, $secret_key, $get_variables, $post_hash="") | |
| Calculate the HMAC for the query. | |
| calculate_posthash ($postdata, $algo) | |
| Calculate a hash for some post data. | |
| cache_hmac_check_replay ($hmac) | |
| This function will do two things. | |
| get_api_user ($site_guid, $api_key) | |
| Find an API User's details based on the provided public api key. | |
| remove_api_user ($site_guid, $api_key) | |
| Revoke an api user key. | |
| create_api_user ($site_guid) | |
| Generate a new API user for a site, returning a new keypair on success. | |
| get_and_validate_api_headers () | |
| This function looks at the super-global variable $_SERVER and extracts the various header variables needed to pass to the validation functions after performing basic validation. | |
| get_post_data () | |
| Return a sanitised form of the POST data sent to the script. | |
| pam_auth_usertoken ($credentials=NULL) | |
| Function that examines whether an authentication token is present returning true if it is, OR the requested method doesn't require one. | |
| pam_auth_anonymous_method ($credentials=NULL) | |
| Test to see whether a given function has been declared as anonymous access (it doesn't require any auth token). | |
| pam_auth_session ($credentials=NULL) | |
| See if the user has a valid login sesson. | |
| pam_auth_hmac ($credentials=NULL) | |
| Secure authentication through headers and HMAC. | |
| pam_auth_session_or_hmac ($credentials=NULL) | |
| A bit of a hack. | |
| serialise_api_headers (array $headers) | |
| Utility function to serialise a header array into its text representation. | |
| send_api_call (array $keys, $url, array $call, $method= 'GET', $post_data= '', $content_type= 'application/octet-stream') | |
| Send a raw API call to an elgg api endpoint. | |
| send_api_get_call ($url, array $call, array $keys) | |
| Send a GET call. | |
| send_api_post_call ($url, array $call, array $keys, $post_data, $content_type= 'application/octet-stream') | |
| Send a GET call. | |
| get_standard_api_key_array ($secret_key, $api_key) | |
| Return a key array suitable for the API client using the standard authentication method based on api-keys and secret keys. | |
| __php_api_error_handler ($errno, $errmsg, $filename, $linenum, $vars) | |
| PHP Error handler function. | |
| __php_api_exception_handler ($exception) | |
| PHP Exception handler. | |
| api_init () | |
| Initialise the API subsystem. | |
| api_endpoint_handler ($page) | |
| Register a page handler for the various API endpoints. | |
Variables | |
| $METHODS = array() | |
| An array holding methods. | |
| $APICLIENT_LAST_CALL = NULL | |
| $APICLIENT_LAST_CALL_RAW = "" | |
| $APICLIENT_LAST_ERROR = NULL | |
| $ERRORS = array() | |
| Define a global array of errors. | |
| __php_api_error_handler | ( | $ | errno, | |
| $ | errmsg, | |||
| $ | filename, | |||
| $ | linenum, | |||
| $ | vars | |||
| ) |
PHP Error handler function.
This function acts as a wrapper to catch and report PHP error messages.
| unknown_type | $errno | |
| unknown_type | $errmsg | |
| unknown_type | $filename | |
| unknown_type | $linenum | |
| unknown_type | $vars |
| __php_api_exception_handler | ( | $ | exception | ) |
PHP Exception handler.
This is a generic exception handler for PHP exceptions. This will catch any uncaught exception and return it as an ErrorResult in the requested format.
| Exception | $exception |
Definition at line 1172 of file api.php.
References ErrorResult.$RESULT_FAIL, elgg_view(), ErrorResult.getInstance(), and page_draw().
| api_endpoint_handler | ( | $ | page | ) |
Register a page handler for the various API endpoints.
| array | $page |
Definition at line 1202 of file api.php.
References $CONFIG, $page, and elgg_set_viewtype().
| api_init | ( | ) |
Initialise the API subsystem.
Definition at line 1191 of file api.php.
References register_page_handler().
| auth_gettoken | ( | $ | username, | |
| $ | password | |||
| ) |
The auth.gettoken API.
This API call lets a user log in, returning an authentication token which can be used in leu of a username and password login from then on.
| string | username Username | |
| string | password Clear text password |
Definition at line 587 of file api.php.
References $password, $token, $username, authenticate(), elgg_echo(), and obtain_user_token().
| cache_hmac_check_replay | ( | $ | hmac | ) |
This function will do two things.
Firstly it verifys that a $hmac hasn't been seen before, and secondly it will add the given hmac to the cache.
| $hmac | The hmac string. |
Definition at line 691 of file api.php.
Referenced by pam_auth_hmac().
| calculate_hmac | ( | $ | algo, | |
| $ | time, | |||
| $ | api_key, | |||
| $ | secret_key, | |||
| $ | get_variables, | |||
| $ | post_hash = "" | |||
| ) |
Calculate the HMAC for the query.
This function signs an api request using the information provided and is then verified by searunner.
| $algo | string The HMAC algorithm used as stored in X-Searunner-hmac-algo. | |
| $time | string String representation of unix time as stored in X-Searunner-time. | |
| $api_key | string Your api key. | |
| $secret | string Your secret key. | |
| $get_variables | string URLEncoded string representation of the get variable parameters, eg "format=php&method=searunner.test". | |
| $post_hash | string Optional sha1 hash of the post data. |
Definition at line 649 of file api.php.
References $CONFIG, $time, and map_api_hash().
Referenced by pam_auth_hmac(), and send_api_call().
| calculate_posthash | ( | $ | postdata, | |
| $ | algo | |||
| ) |
Calculate a hash for some post data.
TODO: Work out how to handle really large bits of data.
| $postdata | string The post data. | |
| $algo | string The algorithm used. |
Definition at line 675 of file api.php.
References map_api_hash().
Referenced by pam_auth_hmac(), and send_api_call().
| create_api_user | ( | $ | site_guid | ) |
Generate a new API user for a site, returning a new keypair on success.
| int | $site_guid The GUID of the site. |
Definition at line 744 of file api.php.
References $CONFIG, get_api_user(), and insert_data().
| execute_method | ( | $ | method, | |
| array $ | parameters, | |||
| $ | token = "" | |||
| ) |
Executes a method.
A method is a function which you have previously exposed using expose_function.
| string | $method Method, e.g. "foo.bar" | |
| array | $parameters Array of parameters in the format "variable" => "value", thse will be sanitised before being fed to your handler. | |
| string | $token The authentication token to authorise this method call. |
| APIException,SecurityException |
Definition at line 450 of file api.php.
References $CONFIG, $method, $METHODS, $result, $token, elgg_echo(), get_call_method(), SuccessResult.getInstance(), and sanitise_string().
| expose_function | ( | $ | method, | |
| $ | function, | |||
| array $ | parameters = NULL, |
|||
| $ | description = "", |
|||
| $ | call_method = "GET", |
|||
| $ | require_auth_token = true, |
|||
| $ | anonymous = false | |||
| ) |
Expose an arbitrary function as an api call.
Limitations: Currently can not expose functions which expect objects.
| string | $method The api name to expose this as, eg "myapi.dosomething" | |
| string | $function Your function callback. | |
| array | $parameters Optional list of parameters in the same order as in your function, with optional parameters last. This array should be in the format "variable" = array ( type => 'int' | 'bool' | 'float' | 'string' | 'array' required => true (default) | false ) | |
| string | $description Optional human readable description of the function. | |
| string | $call_method Define what call method should be used for this function. | |
| bool | $require_auth_token Whether this requires a user authentication token or not (default is true). | |
| bool | $anonymous Can anonymous (non-authenticated in any way) users execute this call. |
Definition at line 403 of file api.php.
References $description, $method, $METHODS, and elgg_echo().
Referenced by notification_init().
| get_and_validate_api_headers | ( | ) |
This function looks at the super-global variable $_SERVER and extracts the various header variables needed to pass to the validation functions after performing basic validation.
| APIException | Detailing any error. |
Definition at line 766 of file api.php.
References $result, elgg_echo(), get_call_method(), get_input(), and get_parameters_for_method().
Referenced by pam_auth_hmac().
| get_api_user | ( | $ | site_guid, | |
| $ | api_key | |||
| ) |
Find an API User's details based on the provided public api key.
These users are not users in the traditional sense.
| int | $site_guid The GUID of the site. | |
| string | $api_key The API Key |
Definition at line 712 of file api.php.
References $CONFIG, get_data_row(), and sanitise_string().
Referenced by create_api_user(), pam_auth_hmac(), and remove_api_user().
| get_call_method | ( | ) |
Get the request method.
Definition at line 301 of file api.php.
Referenced by execute_method(), and get_and_validate_api_headers().
| get_parameters_for_method | ( | $ | method | ) |
This function analyses all expected parameters for a given method, returning them in an associated array from input.
This ensures that they are sanitised and that no superfluous commands are registered. It also means that hmacs work through the page handler.
| string | $method The method |
Definition at line 316 of file api.php.
References $CONFIG, $method, $METHODS, get_input(), and sanitise_string().
Referenced by get_and_validate_api_headers().
| get_post_data | ( | ) |
Return a sanitised form of the POST data sent to the script.
Definition at line 819 of file api.php.
Referenced by pam_auth_hmac().
| get_standard_api_key_array | ( | $ | secret_key, | |
| $ | api_key | |||
| ) |
| list_all_apis | ( | ) |
| map_api_hash | ( | $ | algo | ) |
Map various algorithms to their PHP equivs.
This also gives us an easy way to disable algorithms.
| string | $algo The algorithm |
| APIException | if an algorithm is not supported. |
Definition at line 620 of file api.php.
References elgg_echo(), and sanitise_string().
Referenced by calculate_hmac(), and calculate_posthash().
| obtain_user_token | ( | $ | username, | |
| $ | password | |||
| ) |
Obtain a token for a user.
| string | $username The username | |
| string | $password The password |
Definition at line 338 of file api.php.
References $CONFIG, $password, $site, $time, $token, $user, $username, get_user_by_username(), and insert_data().
Referenced by auth_gettoken().
| pam_auth_anonymous_method | ( | $ | credentials = NULL |
) |
| pam_auth_hmac | ( | $ | credentials = NULL |
) |
Secure authentication through headers and HMAC.
Definition at line 898 of file api.php.
References $CONFIG, $params, ErrorResult.$RESULT_FAIL_APIKEY_INVALID, cache_hmac_check_replay(), calculate_hmac(), calculate_posthash(), elgg_echo(), get_and_validate_api_headers(), get_api_user(), and get_post_data().
Referenced by pam_auth_session_or_hmac().
| pam_auth_session | ( | $ | credentials = NULL |
) |
See if the user has a valid login sesson.
Definition at line 890 of file api.php.
References isloggedin().
Referenced by pam_auth_session_or_hmac().
| pam_auth_session_or_hmac | ( | $ | credentials = NULL |
) |
A bit of a hack.
Basically, this combines session and hmac, so that one of them must evaluate to true in order to proceed.
This ensures that this and auth_token are evaluated separately.
| unknown_type | $credentials |
Definition at line 966 of file api.php.
References pam_auth_hmac(), and pam_auth_session().
| pam_auth_usertoken | ( | $ | credentials = NULL |
) |
Function that examines whether an authentication token is present returning true if it is, OR the requested method doesn't require one.
If a token is present and a validated user id is returned, that user is logged in to the current session.
| unknown_type | $credentials |
Definition at line 844 of file api.php.
References $CONFIG, $method, $METHODS, ErrorResult.$RESULT_FAIL_AUTHTOKEN, $token, $u, elgg_echo(), get_entity(), get_input(), isloggedin(), login(), and validate_user_token().
| remove_api_user | ( | $ | site_guid, | |
| $ | api_key | |||
| ) |
Revoke an api user key.
| int | $site_guid The GUID of the site. | |
| string | $api_key The API Key (public). |
Definition at line 728 of file api.php.
References $CONFIG, delete_data(), and get_api_user().
| send_api_call | ( | array $ | keys, | |
| $ | url, | |||
| array $ | call, | |||
| $ | method = 'GET', |
|||
| $ | post_data = '', |
|||
| $ | content_type = 'application/octet-stream' | |||
| ) |
Send a raw API call to an elgg api endpoint.
| array | $keys The api keys. | |
| string | $url URL of the endpoint. | |
| array | $call Associated array of "variable" => "value" | |
| string | $method GET or POST | |
| string | $post_data The post data | |
| string | $content_type The content type |
Definition at line 1010 of file api.php.
References $APICLIENT_LAST_CALL, $APICLIENT_LAST_CALL_RAW, $APICLIENT_LAST_ERROR, $CONFIG, $content_type, $context, $method, $params, $time, $url, calculate_hmac(), calculate_posthash(), elgg_echo(), and serialise_api_headers().
Referenced by send_api_get_call(), and send_api_post_call().
| send_api_get_call | ( | $ | url, | |
| array $ | call, | |||
| array $ | keys | |||
| ) |
Send a GET call.
| string | $url URL of the endpoint. | |
| array | $call Associated array of "variable" => "value" | |
| array | $keys The keys dependant on chosen authentication method |
Definition at line 1100 of file api.php.
References $url, and send_api_call().
| send_api_post_call | ( | $ | url, | |
| array $ | call, | |||
| array $ | keys, | |||
| $ | post_data, | |||
| $ | content_type = 'application/octet-stream' | |||
| ) |
Send a GET call.
| string | $url URL of the endpoint. | |
| array | $call Associated array of "variable" => "value" | |
| array | $keys The keys dependant on chosen authentication method | |
| string | $post_data The post data | |
| string | $content_type The content type |
Definition at line 1112 of file api.php.
References $content_type, $url, and send_api_call().
Referenced by ping_home().
| serialise_api_headers | ( | array $ | headers | ) |
Utility function to serialise a header array into its text representation.
| $headers | array The array of headers "key" => "value" |
Definition at line 989 of file api.php.
Referenced by send_api_call().
| validate_user_token | ( | $ | site, | |
| $ | token | |||
| ) |
Validate a token against a given site.
A token registered with one site can not be used from a different apikey(site), so be aware of this during development.
| int | $site The ID of the site | |
| string | $token The Token. |
Definition at line 366 of file api.php.
References $CONFIG, $site, $time, $token, $user, elgg_echo(), get_data_row(), and sanitise_string().
Referenced by pam_auth_usertoken().
| $APICLIENT_LAST_CALL = NULL |
| $APICLIENT_LAST_CALL_RAW = "" |
| $APICLIENT_LAST_ERROR = NULL |
| $ERRORS = array() |
Define a global array of errors.
Definition at line 1125 of file api.php.
Referenced by __php_api_error_handler(), and GenericResult.export().
| $METHODS = array() |
An array holding methods.
The structure of this is $METHODS = array ( "api.method" => array ( "function" = 'my_function_callback' "call_method" = 'GET' | 'POST' "parameters" = array ( "variable" = array ( // NB, the order is the same as defined by your function callback type => 'int' | 'bool' | 'float' | 'string' required => true (default) | false ) ) "require_auth_token" => true (default) | false "description" => "Some human readable description" ) )
Definition at line 296 of file api.php.
Referenced by execute_method(), expose_function(), get_parameters_for_method(), list_all_apis(), pam_auth_anonymous_method(), and pam_auth_usertoken().
1.5.6