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 | MAX_REQUEST_RECIPIENTS | The maximum number of recipients for a gift/request.
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 MAX_REQUEST_RECIPIENTS

The maximum number of recipients for a gift/request.

Constant Value: 8 (0x00000008)

#### 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

- `PendingResult` to access the data when available.

#### 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

- `PendingResult` to access the data when available.

#### 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

- `PendingResult` to access the data when available.

#### 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

- `PendingResult` to access the data when available.

#### 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

- An `ArrayList` of `GameRequest` objects that were selected for action.

#### 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

- An `ArrayList` of `GameRequest` objects that were selected for action in the request inbox.

##### See Also

- `getGameRequestsFromBundle(android.os.Bundle)`

#### 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

- `PendingResult` to access the data when available.

#### 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.