public interface

Requests

com.google.android.gms.games.request.Requests

Class Overview

Entry point for request functionality.

Summary

Nested Classes
interface Requests.LoadRequestsResult Result delivered when requests have loaded. 
interface Requests.UpdateRequestsResult Result delivered when requests are updated. 
Constants
String EXTRA_REQUESTS Used to return a list of GameRequest objects.
int REQUEST_DEFAULT_LIFETIME_DAYS Value used to signal the server to use the default request lifetime.
int REQUEST_DIRECTION_INBOUND Load only inbound requests (where the loading player is the recipient).
int REQUEST_DIRECTION_OUTBOUND Load only outbound requests (where the loading player is the sender).
int REQUEST_UPDATE_OUTCOME_FAIL Constant indicating that the request update failed.
int REQUEST_UPDATE_OUTCOME_RETRY Constant indicating that the request update failed but should be retried.
int REQUEST_UPDATE_OUTCOME_SUCCESS Constant indicating that the request update was a success.
int REQUEST_UPDATE_TYPE_ACCEPT Constant indicating that the request should be accepted.
int REQUEST_UPDATE_TYPE_DISMISS Constant indicating that the request should be dismissed.
int SORT_ORDER_EXPIRING_SOON_FIRST Sort requests with the requests expiring soonest first.
int SORT_ORDER_SOCIAL_AGGREGATION Sort requests such that requests from players in the user's circles are returned first.
Public Methods
abstract PendingResult<Requests.UpdateRequestsResult> acceptRequest(GoogleApiClient apiClient, String requestId)
Accepts the specified request.
abstract PendingResult<Requests.UpdateRequestsResult> acceptRequests(GoogleApiClient apiClient, List<String> requestIds)
Accepts the specified requests as a batch operation.
abstract PendingResult<Requests.UpdateRequestsResult> dismissRequest(GoogleApiClient apiClient, String requestId)
Dismisses the specified request.
abstract PendingResult<Requests.UpdateRequestsResult> dismissRequests(GoogleApiClient apiClient, List<String> requestIds)
Dismisses the specified requests as a batch operation.
abstract ArrayList<GameRequest> getGameRequestsFromBundle(Bundle extras)
This method takes a Bundle object and extracts the GameRequest list provided.
abstract ArrayList<GameRequest> getGameRequestsFromInboxResponse(Intent response)
This method takes an Intent object and extracts the GameRequest list provided as an extra.
abstract Intent getInboxIntent(GoogleApiClient apiClient)
Returns an intent that will let the user see and manage any outstanding requests.
abstract int getMaxLifetimeDays(GoogleApiClient apiClient)
Gets the maximum lifetime of a request in days.
abstract int getMaxPayloadSize(GoogleApiClient apiClient)
Gets the maximum data size of a request payload in bytes.
abstract Intent getSendIntent(GoogleApiClient apiClient, int type, byte[] payload, int requestLifetimeDays, Bitmap icon, String description)
Returns an intent that will let the user send a request to another player.
abstract PendingResult<Requests.LoadRequestsResult> loadRequests(GoogleApiClient apiClient, int requestDirection, int types, int sortOrder)
Loads requests for the current game.
abstract void registerRequestListener(GoogleApiClient apiClient, OnRequestReceivedListener listener)
Register a listener to intercept incoming requests for the currently signed-in user.
abstract void unregisterRequestListener(GoogleApiClient apiClient)
Unregisters this client's request listener, if any.

Constants

public static final String EXTRA_REQUESTS

Used to return a list of GameRequest objects. Retrieve with getParcelableArrayListExtra(String) or getParcelableArrayList(String).

Constant Value: "requests"

public static final int REQUEST_DEFAULT_LIFETIME_DAYS

Value used to signal the server to use the default request lifetime.

Constant Value: -1 (0xffffffff)

public static final int REQUEST_DIRECTION_INBOUND

Load only inbound requests (where the loading player is the recipient).

Constant Value: 0 (0x00000000)

public static final int REQUEST_DIRECTION_OUTBOUND

Load only outbound requests (where the loading player is the sender).

Constant Value: 1 (0x00000001)

public static final int REQUEST_UPDATE_OUTCOME_FAIL

Constant indicating that the request update failed.

Constant Value: 1 (0x00000001)

public static final int REQUEST_UPDATE_OUTCOME_RETRY

Constant indicating that the request update failed but should be retried.

Constant Value: 2 (0x00000002)

public static final int REQUEST_UPDATE_OUTCOME_SUCCESS

Constant indicating that the request update was a success.

Constant Value: 0 (0x00000000)

public static final int REQUEST_UPDATE_TYPE_ACCEPT

Constant indicating that the request should be accepted.

Constant Value: 0 (0x00000000)

public static final int REQUEST_UPDATE_TYPE_DISMISS

Constant indicating that the request should be dismissed.

Constant Value: 1 (0x00000001)

public static final int SORT_ORDER_EXPIRING_SOON_FIRST

Sort requests with the requests expiring soonest first.

Constant Value: 0 (0x00000000)

public static final int SORT_ORDER_SOCIAL_AGGREGATION

Sort requests such that requests from players in the user's circles are returned first.

Constant Value: 1 (0x00000001)

Public Methods

public abstract PendingResult<Requests.UpdateRequestsResult> acceptRequest (GoogleApiClient apiClient, String requestId)

Accepts the specified request. If the result of this operation is REQUEST_UPDATE_OUTCOME_SUCCESS, the player successfully accepted the request.

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
requestId The ID of the request to accept.
Returns

public abstract PendingResult<Requests.UpdateRequestsResult> acceptRequests (GoogleApiClient apiClient, List<String> requestIds)

Accepts the specified requests as a batch operation. If the result of this operation is REQUEST_UPDATE_OUTCOME_SUCCESS, the player successfully accepted the requests.

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
requestIds The IDs of the requests to accept.
Returns

public abstract PendingResult<Requests.UpdateRequestsResult> dismissRequest (GoogleApiClient apiClient, String requestId)

Dismisses the specified request. If the result of this operation is REQUEST_UPDATE_OUTCOME_SUCCESS, the request will be deleted from local storage. Note that dismissing a request does not inform the sender of the action.

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
requestId The ID of the request to dismiss.
Returns

public abstract PendingResult<Requests.UpdateRequestsResult> dismissRequests (GoogleApiClient apiClient, List<String> requestIds)

Dismisses the specified requests as a batch operation. If the result of this operation is REQUEST_UPDATE_OUTCOME_SUCCESS, the requests will be deleted from local storage. Note that dismissing a request does not inform the sender of the action.

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
requestIds The ID of the requests to dismiss.
Returns

public abstract ArrayList<GameRequest> getGameRequestsFromBundle (Bundle extras)

This method takes a Bundle object and extracts the GameRequest list provided. If the Bundle is invalid or does not contain the correct data, this method returns an empty list.

Parameters
extras The Bundle to parse for GameRequest objects.
Returns

public abstract ArrayList<GameRequest> getGameRequestsFromInboxResponse (Intent response)

This method takes an Intent object and extracts the GameRequest list provided as an extra. Specifically, this method is useful in parsing the returned Intent that was returned as the response from the request inbox Intent. If the Intent is invalid or does not contain the correct extra data, this method returns an empty list.

Parameters
response The Intent response from the requests inbox.
Returns
See Also

public abstract Intent getInboxIntent (GoogleApiClient apiClient)

Returns an intent that will let the user see and manage any outstanding requests. Note that this must be invoked using startActivityForResult(Intent, int) so that the identity of the calling package can be established.

If the user canceled, the result will be RESULT_CANCELED. If the user selected any requests to accept, the result will be RESULT_OK and the data intent will contain the selected requests as a parcelable extra in EXTRA_REQUESTS.

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
Returns
  • An Intent that can be started to view the request inbox UI.

public abstract int getMaxLifetimeDays (GoogleApiClient apiClient)

Gets the maximum lifetime of a request in days. This is guaranteed to be at least 14 days.

If the service cannot be reached for some reason, this will return -1.

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
Returns
  • The maximum request lifetime in days.

public abstract int getMaxPayloadSize (GoogleApiClient apiClient)

Gets the maximum data size of a request payload in bytes. Guaranteed to be at least 2 KB. May increase in the future.

If the service cannot be reached for some reason, this will return -1.

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
Returns
  • The maximum data size per request in bytes.

public abstract Intent getSendIntent (GoogleApiClient apiClient, int type, byte[] payload, int requestLifetimeDays, Bitmap icon, String description)

Returns an intent that will let the user send a request to another player. Note that this must be invoked using startActivityForResult(Intent, int) so that the identity of the calling package can be established.

Players may be preselected by specifying a list of player IDs in the EXTRA_PLAYER_IDS extra on the returned intent.

If the user canceled, the result will be RESULT_CANCELED. If the request was sent successfully, the result will be RESULT_OK. If the request could not be sent, the result will be RESULT_SEND_REQUEST_FAILED.

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
type The type of the request to send. May be either TYPE_GIFT or TYPE_WISH.
payload A byte array of data to send with the request. May be a maximum of getMaxPayloadSize(GoogleApiClient) bytes.
requestLifetimeDays How long (in days) this request should last if the recipient takes no action. Must be at least 1 day and no more than getMaxLifetimeDays(GoogleApiClient). To use the server default, use REQUEST_DEFAULT_LIFETIME_DAYS.
icon A Bitmap to display as the request icon.
description String describing the item. Displayed to the user to add context.
Returns
  • An Intent that can be started to launch the "Send Request" UI.

public abstract PendingResult<Requests.LoadRequestsResult> loadRequests (GoogleApiClient apiClient, int requestDirection, int types, int sortOrder)

Loads requests for the current game. Requests with any of the specified types will be returned.

Possible types include TYPE_GIFT or TYPE_WISH. Types may be joined together as a bitmask to request multiple types.

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
requestDirection The direction of requests to load. Must be either REQUEST_DIRECTION_INBOUND or REQUEST_DIRECTION_OUTBOUND.
types Mask indicating the types of requests to load.
sortOrder The sort order to use for sorting the requests. Must be either SORT_ORDER_EXPIRING_SOON_FIRST or SORT_ORDER_SOCIAL_AGGREGATION.
Returns

public abstract void registerRequestListener (GoogleApiClient apiClient, OnRequestReceivedListener listener)

Register a listener to intercept incoming requests for the currently signed-in user. If a listener is registered by this method, the incoming request will not generate a status bar notification as long as this client remains connected.

Note that only one request listener may be active at a time. Calling this method while another request listener was previously registered will replace the original listener with the new one.

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.
listener The listener that is called when a new request is received. The listener is called on the main thread.

public abstract void unregisterRequestListener (GoogleApiClient apiClient)

Unregisters this client's request listener, if any. Any new requests will generate status bar notifications as normal.

Required API: API
Required Scopes: SCOPE_GAMES

Parameters
apiClient The GoogleApiClient to service the call.