Define extension provisioning keys
OEMs can extend the runtime configuration engine to trigger provisioning based on custom data (although the timing of an extension event can coincide with UICC events). The runtime configuration extension handler checks for extension provisioning events by reading a list of values in the registry. These paths map to configuration service provider settings, which the extension handler queries to retrieve values to search for in the provisioning datastores. OEMs can use this mechanism to add more Conditions to key off when specifying the TargetState. For more information about conditions and target states, see Customization answer file.
OEMs must configure extension provisioning event keys in .reg files or in static XML files that run during cold boot. For example, in the scenario in which a mobile operator supports mobile virtual network operators (MVNOs), MCC, MNC, and SPN values may not be enough to differentiate a hypothetical mobile operator "Contoso" from an MVNO "Fabrikam". In this scenario, OEMs can use other code that is running on the phone to create a key that the runtime configuration engine can use to further differentiate Contoso from Fabrikam.
Defining an extension handler registry key
To define an extension handler registry key, OEMs must add an HKEY_LOCAL_MACHINE\Software\OEM\ADC\CustomizationKeys\<ExtensionName> registry key. <ExtensionName> is the friendly name of the extension, such as MVNO-Lookup.
The data in this registry value must map to a device management path to the keyed value, such as "./DevDetail/SwV". The MVNO extension will use the DevDetail configuration service provider's Software Version (SwV), such as "8.4.5.6", as the key to find values in the root datastore.
Note
To retrieve the ICCID and IMSI for a dual SIM phone, see the Retrieving ICCID and IMSI for a dual SIM phone sample in Samples for writing a custom configuration service provider.
The following table describes the registry subkeys and types that you can use to define an extension handler registry key.
| Key | Registry type | Description |
|---|---|---|
Order |
REG_DWORD |
Specifies the order that keys in the <ExtensionName> are queried. A lower value represents a higher order. |
ProvisionState |
Registry subkey |
This registry subkey has one or more subvalues, each corresponding to a provision state that this extension can support. For example, "Uicc_General"=REG_SZ:"Any value". The following is the list of ProvisionState values:
OEMs can use extension keys or conditions to determine device state mixed with UICC-based values (such as MCC, MNC, and SPN). |
Keys |
Registry subkey |
This registry subkey has one or more subvalues, where the name corresponds to the key name in the source datastore query and the registry value corresponds to a configuration service provider URI. For instance, in the example, “MVNO”=REG_SZ:”./Vendor/Microsoft/CSP/GetMvno”.The corresponding source database rule could be $(MVNO)="Fabrikam". |
PreviousValues |
Registry subkey |
(Dynamic) This is a registry subkey. Each subvalue corresponds to the last queried value from "Keys". This subkey is generated by runtime configuration during runtime. This subkey is unlike the other registry keys, which are set at build time or provisioning time. In the previous example, "MVNO"=REG_SZ:<Previous Value>. |
Examples
UI runtime configuration stage
The following example shows the registry keys you need to add the UI stage to your registry if you want your extension key to participate in the UI picker selections:
HKEY_LOCAL_MACHINE\software\oem\adc\customizationkeys\deviceextension
Order REG_DWORD 0x64
HKEY_LOCAL_MACHINE\software\oem\adc\customizationkeys\deviceextension\Keys
DeviceType REG_SZ ./Vendor/MSFT/Registry/HKLM/SYSTEM/Platform/DeviceTargetingInfo/PhoneSOCVersion
HKEY_LOCAL_MACHINE\software\oem\adc\customizationkeys\deviceextension\ProvisionState
Uicc_RunOnce REG_SZ Uicc_RunOnce
To get the DeviceType included as a key when searching for the UI, you must update the ProvisionState registry key with a UI entry, as shown in the following example:
HKEY_LOCAL_MACHINE\software\oem\adc\customizationkeys\deviceextension\ProvisionState
Uicc_RunOnce REG_SZ Uicc_RunOnce
UI REG_SZ UI
Define an extension key in the customization answer file
The following example shows how an OEM can use a defined extension key in the customization answer file:
<Target Id="SomeMO">
<TargetState>
<Condition Name="ImsiGroup" Value="ThePhoneCompany" />
</TargetState>
</Target>
Define the ImsiGroup on the phone
To define the ImsiGroup registry key on the phone, an OEM can use the following registry content:
; Example extension key definition
[HKEY_LOCAL_MACHINE\software\oem\adc\customizationkeys]
[HKEY_LOCAL_MACHINE\software\oem\adc\customizationkeys\ImsiRangeExtension]
"Order"=dword:00000064
; ImsiRangeExtension doesn't have to match the condition/key described in the customization answers file. It's just a placeholder here.
; The key name doesn't have to match the configuration service provider name.
[HKEY_LOCAL_MACHINE\software\oem\adc\customizationkeys\ImsiRangeExtension\Keys]
"ImsiGroup"="./Vendor/MSFT/SimUtilCSP/ImsiGroup"
[HKEY_LOCAL_MACHINE\software\oem\adc\customizationkeys\ImsiRangeExtension\ProvisionState]
"Uicc_Connectivity"="Uicc_Connectivity"