A request to Permission Nanny to access resources that are protected by Android permissions on your behalf.
Request Types
Requests can be classified into 2 categories -
SimpleRequest
and
ContentRequest
.
Requests handled by dedicated Android managers - such as
TelephonyManager
and
SmsManager
- are considered simple requests.
Use one of the subclass factories - such as
ContentRequest
and
LocationRequest
- to create requests.
To minimize confusion, each request factory closely mimics Android's managers. eg:
LocationRequest
mimics
LocationManager
,
WifiRequest
mimics
WifiManager
. The
creator methods exposed in request factories also mirror those in Android managers.
How to Listen for a Response for a SimpleRequest
After creating a request, attach a listener to it via
SimpleRequest.listener(SimpleListener)
to receive
results for a request. No matter if the user allows or denies your request, Permission Nanny will return the results
in a Bundle. The response Bundle consists of 2 components: metadata entries describing the response such as
Nanny.PROTOCOL_VERSION
and
Nanny.STATUS_CODE
; and entity data which contains the requested resource. Entity
data is structured as a nested Bundle within the response Bundle indexed at
Nanny.ENTITY_BODY
. If Permission
Nanny encountered a failure while executing your request, a nested
NannyException
indexed at
Nanny.ENTITY_ERROR
will provide you details of what went wrong.
For one-shot requests, the requested resource is indexed using the method name within the entity data Bundle. For
example, if you were to make a
WifiRequest.getConnectionInfo()
request, the resource would be indexed at
WifiRequest.GET_CONNECTION_INFO
within a Bundle indexed at
Nanny.ENTITY_BODY
of the response Bundle.
WifiRequest request = WifiRequest.getConnectionInfo().listener(new SimpleListener() {
public void onResponse(Bundle response) {
Bundle entity = response.getBundle(Nanny.ENTITY_BODY);
if (Nanny.SC_OK != response.getInt(Nanny.STATUS_CODE)) {
NannyException error = (NannyException) entity.getSerializable(Nanny.ENTITY_ERROR);
return;
}
WifiInfo info = entity.getParcelable(WifiRequest.GET_CONNECTION_INFO);
}
}).startRequest(context, "Trust me");
For ongoing requests that require you to provide an Android listener - such as
LocationRequest.requestLocationUpdates(long, float, Criteria, LocationListener, Looper)
, the response Bundle will
only contain metadata and no entity data because the resource is delivered directly to the listener interface
provided to the request.
Requests handled by
ContentProvider
s and
ContentResolver
s are
considered content requests.
Use a
ContentRequest.Builder
to craft your query. The parameters the builder accepts closely resembles to
ContentResolver
queries. As of now, only simple queries such as .query(), .insert(),
.update() and .delete() are supported; .applyBatch() and .bulkInsert() are not supported
yet.
How to Listen for a Response for a ContentRequest
After creating a request, attach a listener via
ContentRequest.listener(ContentListener)
to receive results
for a request. Similar to
SimpleRequest
s, Permission Nanny will return response metadata in a Bundle.
Resources are delivered via the appropriate parameter depending on the type of the content request.
ContentRequest request = ContentRequest.newBuilder().select()
.uri(ContactsContract.Contacts.CONTENT_URI)
.sortOrder(BaseColumns._ID + " limit 5")
.build();
request.listener(new ContentListener() {
public void onResponse(@NonNull Bundle response, Cursor data, Uri inserted, int rowsUpdated, int rowsDeleted) {
Bundle entity = response.getBundle(Nanny.ENTITY_BODY);
if (Nanny.SC_OK != response.getInt(Nanny.STATUS_CODE)) {
NannyException error = (NannyException) entity.getSerializable(Nanny.ENTITY_ERROR);
return;
}
String[] columns = data.getColumnNames();
}
}).startRequest(context, "Trust me");
How to Start a Request
Send the request to Permission Nanny via
startRequest(Context, String)
.