1

I'm learning the new Contact Tracing API that Apple is releasing for iOS (in partnership with Google).

I'm not gasping the relationship of the maxKeyCount property on the CTExposureDetectionSession, and its relationship with the addPositiveDiagnosisKeys: completion: method.

What I understand

A CTExposureDetectionSession is the object that allows an app to ask the framework to start trying to match a list of published Diagnosis Keys against the local database of captured Rolling Proximity Identifiers.

The app would start by calling the activateWithCompletion: method on a new session, and then call addPositiveDiagnosisKeys: one or more times, to eventually inform the framework that no more keys are to be added by calling finishedPositiveDiagnosisKeysWithCompletion:.

That last call will also indicate the block to run upon detection completion, which will be called with a CTExposureDetectionSummary object informing the amount of Diagnosis Keys that the device has been exposed to.

What I do not understand

The maxKeyCount property doc says:

This property contains the maximum number of keys to provide to this API at once. This property’s value updates after each operation complete and before the completion handler is invoked. Use this property to throttle key downloads to avoid excessive buffering of keys in memory.

But the addPositiveDiagnosisKeys: method says:

Asynchronously adds the specified keys to the session to allow them to be checked for exposure. Each call to this method must include more keys than specified by the current value of <maxKeyCount>.

maxKeyCount seems to be a maximum, but the addPositiveDiagnosisKeys: requires me to call it with more keys than the maximum.

Am I expected to call the method with a superlist of the previously sent list? That doesn't seem to fit well with the "avoid excessive buffering of keys in memory" part - if I have to use an ever-growing list of keys.

And what does the This property’s value updates after each operation complete part?

mgarciaisaia
  • 14,521
  • 8
  • 57
  • 81
  • I think the word "not" is missing between "must" and "include". – Paulw11 Apr 13 '20 at 21:40
  • And the property would be intended to be read by the app? I create a session, read it's `maxKeyCount`, and split my stream of Diagnosis Keys in batches of that amount? Makes sense now. – mgarciaisaia Apr 13 '20 at 21:42
  • 1
    Exactly. You might have only 1 key, so for that property to be a minimum makes no sense (and its name is "max" :) ) – Paulw11 Apr 13 '20 at 21:44

1 Answers1

1

The documentation of maxKeyCount is missing a not.

The Android Contact Tracing API documentation has an analogous interface:

/**
* Provides a list of diagnosis keys for contact checking. The keys are to be
* provided by a centralized service (e.g. synced from the server).
*
* When invoked after the requestProvideDiagnosisKeys callback, this triggers a * recalculation of contact status which can be obtained via hasContact()
* after the calculation has finished. *
* Should be called with a maximum of N keys at a time. */
Task<Status> provideDiagnosisKeys(List<DailyTracingKey> keys);

/**
* The maximum number of keys to pass into provideDiagnosisKeys at any given * time.
*/
int getMaxDiagnosisKeys();

As Paulw11 suggested in a comment, the maxKeyCount property seems to be a value intended for reading that stats how many Diagnosis Keys are to be sent to the API in a single call for the matching to be performed.

Callers should re-check the value before each call, since it may get updated after each call.

The fixed documentation of addPositiveDiagnosisKeys: should, then, read:

Each call to this method must NOT include more keys than specified by the current value of <maxKeyCount>.

mgarciaisaia
  • 14,521
  • 8
  • 57
  • 81