Merge pull request #113 from ably/111-add-api-to-get-agent-info

Define API for accessing Agent identifier and its components

textile/features.textile

@@ -35,6 +35,7 @@ jump_to:
     - Data types#types
     - Options#options
     - Push notifications#types-push
+    - Client library introspection#introspection
   Interface Definition:
     - Complete API IDL#idl
   Previous version:
@@ -1655,6 +1656,18 @@ h4. DevicePushDetails
 * @(PCP3)@ recipient - a map of string key/value pairs containing details of the push transport and address
 * @(PCP4)@ state - the state of the push registration, one of  @Active@, @Failing@, @Failed@
 
+h3(#introspection). Client library introspection
+
+h4. ClientInformation
+* @(CR1)@ Provides information about the client library and the environment in which it’s running.
+* @(CR2)@ @agents@ static property:
+** @(CR2a)@ Returns a @Dict<String, String?>@ that lists the default key-value entries that the library uses to populate the @Agent@ library identifier, as described by "@RSC7d1@":#RSC7d1. An example would be @{ "ably-java": "1.2.1", "android": "24" }@.
+* @(CR3)@ @agentIdentifier@ static method:
+** @(CR3a)@ The client library must only offer this method if it offers the @ClientOptions#agents@ property described by "@RSC7d6@":#RSC7d6.
+** @(CR3b)@ Returns the @Agent@ library identifier described by "@RSC7d@":#RSC7d.
+** @(CR3c)@ Accepts an @additionalAgents@ parameter of type @Dict<String, String?>?@, whose value is to be interpreted with the same semantics as the @ClientOptions#agents@ property. The @agentIdentifier@ method will inject these agents into the @Agent@ library identifier that it returns.
+** @(CR3d)@ An API commentary must be provided for this method. This commentary must make it clear that this interface is only to be used by Ably-authored SDKs.
+
 h3(#defaults). Client Library defaults
 
 The following default values are configured for the client library:
@@ -2348,6 +2361,10 @@ class DeltaExtras // DE*
 class ReferenceExtras: // REX*
   timeserial: String // REX2a
   type: String //REX2b
+
+class ClientInformation: // CR*
+  +agents: Dict<String, String?> // CR2
+  +agentIdentifier(additionalAgents: Dict<String, String?>?) => String // CR3; interface only offered by some libraries
 </pre>
 
 h2(#old-specs). Old specs