Docs For Class Veriplace

Description

Low-level interface for obtaining a user's location from Veriplace, when using the Veriplace_Client directly rather than the Veriplace API.

User location can only be obtained by referencing a valid Veriplace_User. Users can be identified using the Veriplace_UserDiscoveryAPI.

An OAuth Access Token is required to obtain a User's location, which may be retrieved by redirecting the User Agent to Veriplace as part of the OAuth user authorization process. Access Tokens may be cached.

Located in /Veriplace/Client.php (line 950)

Veriplace_API
   |
   --Veriplace_AsyncCapableAPI
      |
      --Veriplace_GetLocationAPI

Method Summary

string getAuthorizationURI (string $callback, Veriplace_User $user, boolean $immediate)

Veriplace_LocationRequestStatus getCallbackResult ()

Veriplace_Location getLocation (Veriplace_Token $accessToken, Veriplace_User $user, [Veriplace_LocationOptions $options = null], [int $timeoutSeconds = null])

void getLocationAccessToken (Veriplace_User $user)

Veriplace_Location getLocationById (Veriplace_Token $accessToken, Veriplace_User $user, string $id, [Veriplace_LocationOptions $options = null])

array getPermittedUsers ([int $first = 0], [int $max = null], [int $timeout = null])

Veriplace_LocationRequestStatus getResult (Veriplace_LocationRequestStatus $request)

Veriplace_LocationRequestStatus requestLocation (Veriplace_Token $accessToken, Veriplace_User $user, [Veriplace_LocationOptions $options = null], [Veriplace_CallbackOptions $callbackOptions = null], string $callback)

Methods

getAuthorizationURI (line 975)

Get the URI to use for user redirection to get permission to obtain a user's location.

return: The OAuth redirection URI.
throws: Veriplace_UnexpectedException if there was an unexpected I/O error or OAuth error
throws: Veriplace_OAuthException if the server refused the request
access: public

string getAuthorizationURI (string $callback, Veriplace_User $user, boolean $immediate)

string $callback: The OAuth callback URI.
Veriplace_User $user: The user to be located.
boolean $immediate: Should responses return immediately if user interaction would be required?

getCallbackResult (line 1178)

Process the parameters of an HTTP callback that was posted from Veriplace in response to an asynchronous location request.

The resulting Veriplace_LocationRequestStatus object will contain either a location ID (Veriplace_LocationRequestStatus::$locationId) or an error (Veriplace_LocationRequestStatus::$exception). It will not contain the actual location details; Veriplace does not deliver those by callback, for security reasons. Instead, you can pass the location ID to getLocationById() to get the location details.

The status object's Veriplace_AsyncRequestStatus::$id property will return the same unique identifier that was generated by the original request, which you can use to associate any previously stored request state with the result.

To confirm receipt of the callback, this method also sends an immediate HTTP 200 ("OK") response to Veriplace, completing the HTTP response. Do not try to do anything else with the response object after this; if your application returned anything else, or did not respond, Veriplace would repeat the callback.

return: a Veriplace_LocationRequestStatus object
throws: Veriplace_UnexpectedException if the request did not contain valid parameters
access: public

Veriplace_LocationRequestStatus getCallbackResult ()

Redefinition of:

Veriplace_AsyncCapableAPI::getCallbackResult()

getLocation (line 1020)

Get a user's location.

return: the user's location.
throws: Veriplace_UnexpectedException if there was an unexpected I/O error or OAuth error
throws: Veriplace_GetLocationException if the server refused the request
access: public

Veriplace_Location getLocation (Veriplace_Token $accessToken, Veriplace_User $user, [Veriplace_LocationOptions $options = null], [int $timeoutSeconds = null])

OAuthToken $accessToken: The access token permitting the user to be located.
Veriplace_User $user: The user.
Veriplace_LocationOptions $options: An instance of Veriplace_LocationOptions object allowing the location mode and other properties to be overridden for this request, or null to use default options. Note, for compatibility with previous versions, you may also pass a string value for this parameter, which will be taken as a location mode name; this usage is deprecated and will be unsupported in future versions.
int $timeoutSeconds: The number of seconds to wait, or null for no timeout. This parameter is deprecated; you should use the timeoutMilliseconds property of Veriplace_LocationOptions instead.

getLocationAccessToken (line 989)

Get an access token for a previously discovered user, if you already have permission to locate that user.

throws: Veriplace_UnexpectedException if there was an unexpected I/O error or OAuth error
throws: Veriplace_GetLocationNotPermittedException if the permission does not exist
access: public

void getLocationAccessToken (Veriplace_User $user)

Veriplace_User $user

getLocationById (line 1056)

Get a copy of a previously obtained location using the location ID.

return: The user's location.
throws: Veriplace_UnexpectedException if there was an unexpected I/O error or OAuth error
throws: Veriplace_GetLocationException if the server refused the request
access: public

Veriplace_Location getLocationById (Veriplace_Token $accessToken, Veriplace_User $user, string $id, [Veriplace_LocationOptions $options = null])

OAuthToken $accessToken: The same access token from the original location request.
Veriplace_User $user: The user.
string $id: The location ID.
Veriplace_LocationOptions $options: An instance of Veriplace_LocationOptions object which can specify additional information to obtain on the location, and/or a timeout for the request, or null to use default options. Note, for compatibility with previous versions, you may also pass an integer value for this parameter, which will be taken as a timeout (in seconds); this usage is deprecated and will be unsupported in future versions.

getPermittedUsers (line 1197)

Get a list of users who have granted permission for this application to locate them.

return: A list of Veriplace_User objects.
throws: Veriplace_UnexpectedException if there was an unexpected I/O error or OAuth error
throws: Veriplace_UserDiscoveryNotPermittedException if the server refused the request
access: public

array getPermittedUsers ([int $first = 0], [int $max = null], [int $timeout = null])

int $first: The index of the first result, if you want to skip some number of users from the beginning of the list; default is zero.
int $max: The maximum number of results to return; default is null for no limit.
int $timeout: Deprecated and ignored, but retained for backward compatibility. Timeout should not be specified for this request.

getResult (line 1147)

Attempt to retrieve the result of an asynchronous request that was previously submitted with requestLocation(). Use this method if you did not specify a callback URI in the original request.

If the request is still in progress, this will return the same request status object. If the request has completed, either successfully or unsuccessfully, it will return an updated request status object whose Veriplace_AsyncRequestStatus::$ready property will be true, and which will either contain a Veriplace_Location object (Veriplace_LocationRequestStatus::$location) or an error (Veriplace_LocationRequestStatus::$exception).

return: an updated request status object of the same type
throws: Veriplace_UnexpectedException if there was an unexpected OAuth error or I/O error
throws: Veriplace_RequestNotFoundException if the request is no longer valid, i.e. it has expired or the result was already delivered via a callback notification
access: public

Veriplace_LocationRequestStatus getResult (Veriplace_LocationRequestStatus $request)

Veriplace_LocationRequestStatus $request: the original request status object

Redefinition of:

Veriplace_AsyncCapableAPI::getResult()

requestLocation (line 1096)

Submit an asynchronous request for a user's location.

return: An object representing the location request.
throws: Veriplace_UnexpectedException if there was an unexpected I/O error or OAuth error
throws: Veriplace_GetLocationException if the server refused the request
access: public

Veriplace_LocationRequestStatus requestLocation (Veriplace_Token $accessToken, Veriplace_User $user, [Veriplace_LocationOptions $options = null], [Veriplace_CallbackOptions $callbackOptions = null], string $callback)

OAuthToken $accessToken: The access token permitting the user to be located.
Veriplace_User $user: The user.
Veriplace_LocationOptions $options: An instance of Veriplace_LocationOptions object allowing the location mode and other properties to be overridden for this request, or null to use default options. Note, for compatibility with previous versions, you may also pass a string value for this parameter, which will be taken as a location mode name; this usage is deprecated and will be unsupported in future versions.
Veriplace_CallbackOptions $callbackOptions: An optional Veriplace_CallbackOptions object specifying how Veriplace should post the result back to you when ready; null if you will poll for the result. For backward compatibility, you may also pass a simple callback URI as a string.
string $callback: An optional callback URI to which Veriplace should post the result of the request - see getCallbackResult(); if this is null, the application will have to poll for the result with getResult().

Inherited Methods

Inherited From Veriplace_AsyncCapableAPI

Veriplace_AsyncCapableAPI::getCallbackResult()
Veriplace_AsyncCapableAPI::getResult()

Class Constants

Inherited Constants

Inherited from Veriplace_AsyncCapableAPI

Veriplace_AsyncCapableAPI::REQUEST_CREATION_BASE_PATH
Veriplace_AsyncCapableAPI::REQUEST_QUERY_BASE_PATH