Show TOC

Accessing iOS Application SettingsLocate this document in the navigation structure

Use the ApplicationSettings property of the LogonCore instance to access application settings.

  • The application developer cannot instantiate the ApplicationSettings class directly, it is instantiated by the LogonCore component.
  • An instance of this class is available via a LogonCore instance, only if the device is registered with the LogonCore component.
The ApplicationSettings class implements the IReadOnlyDictionary interface (or the equivalent interface/class on other platforms). This allows the application developer to:
  • Iterate through all the stored settings.
  • Use setting names to retrieve setting values.
The ApplicationSettings class guarantees that if an ApplicationSettings instance is available, it is in a consistent and valid state; the values this class stores are validated against a metadata document.
The application developer cannot modify the application settings directly, which is guaranteed by:
  • Implementing the IReadOnlyDictionary interface that provides read-only access to the settings container (new values cannot be added to the settings).
  • Storing values that implement the IReadOnlyProperty interface, which provides read-only access to the individual setting values.
Downloading Application Settings Method
This method:
  • Asynchronously downloads the application settings and metadata of the settings structure from SAP HANA Cloud Platform mobile services or SAP Mobile Platform Server.
  • Validates the downloaded settings against the newly downloaded metadata and persists the new settings and metadata.
  • Always succeeds and never sends a request if the LogonCore is used with Gateway.
-(void)downloadSettingsWithCompletionBlock:(void (^)(NSError*))completionBlock
Updating Writable Application Settings on the Server
This method:
  • Returns the copy of the writable application setting values in a non-mutable dictionary.
  • Guarantees that the application developer cannot edit the application settings directly; the settings stay consistent and valid on the client. However, the application developer can get the mutable version of the settings that are writable, so some or all of those values can be updated on the server.
  • Since properties (objects that store individual settings) cannot be instantiated by application developers, use this method to get access to the writable properties.
  • Only copies of the writable setting values are returned, guaranteeing that modification of the copied properties are not reflected in the stored application settings on the client.
-(NSDictionary*)writableSettings;
Sample Code 
var deviceType = logonCore.ApplicationSettings["DeviceModel"].Value as string;

// Assume the returned value is "Lenovo T530"
// Make a request for the writable settings and modify the same property:

var writableSettings = logonCore.ApplicationSettings.GetWritableSettings();
writableSettings["DeviceModel"].Value = "Surface Pro 3";

// The two properties do not hold the same value; "false" is printed
System.Diagnostics.Debug.WriteLine(logonCore.ApplicationSettings["DeviceModel"].Value == writableSettings["DeviceModel"]);

The writable values are modified on the client in the ApplicationSettings instance only if the modified values are sent to the server, and the server confirms that these values have been updated on the server side. This prevents the application settings from being overwritten on the client.

Send the Modified Writable Settings to the Server Method
This method:
  • Sends the modified writable settings to SAP HANA Cloud Platform mobile services or SAP Mobile Platform Server to asynchronously update server-side settings.
  • Requires the application developer to call the GetWritableSettings method, prior to calling this method, to access the writable properties that hold individual setting values.
  • Does not send requests to the server and always fails, stating that there are no modifications to the settings, if the LogonCore is used with Gateway.
This method ensures that:
  • Only the modified properties are sent to the server.
  • If updating the writable settings fails, then the application settings remain valid and consistent on the client.
  • After successfully updating the writable settings on the server, the settings are downloaded again to ensure that the application settings on the client are in sync with the settings stored on the server. This is necessary since the server might not accept all the values, but still reports success, or modification to one of the property values implies another requires change. Another example: there are nullable boolean values, but sending null in these values results in the server changing these null values to false.
-(void)updateSettings:(NSDictionary*)newSettings completionBlock:(void (^)(NSError*))completionBlock;
Updating Device Information on the Server
Although device information such as model type, subtype, and phone number can be updated by calling the GetWritableSettings method, modifying the relevant properties then calling the UpdateSettingsAsync method, a helper method that supports this particular scenario has been added to the API. This (helper) method offers these benefits to the application developer:
  • No need to call the GetWritableSettings method.
  • No need to know the application setting names that belong to the device settings group.
  • Can use dedicated properties of a class (DeviceInfo) instead of defining device specific settings. The method updates the device settings asynchronously on SAP HANA Cloud Platform mobile services or SAP Mobile Platform Server, and fails if called when using a Gateway connection.

The method accepts a DeviceInfo class instance.

The method should consider only those properties of the DeviceInfo class that have been modified by the application developer, which prevents device information which contain null values on the server that have not been modified by the application developer from being updated. 
-(void)updateDeviceInfo:(MAFDeviceInfo*)deviceInfo completionBlock:(void (^)(NSError*))completionBlock;
Application Connection ID Property
This property:
  • Always returns null if a Gateway connection is used or if the device is not registered
  • Returns the application connection ID from the settings that can normally be found under the "ApplicationConnectionId" key, if the device is registered on SAP HANA Cloud Platform mobile services or SAP Mobile Platform Server
  • Is read-only
MAFApplicationSettings* appSettings = self.logonCore.applicationSettings;


// Retrieving the application connection id as a string from the ApplicationSettings component of the Logon Core instance
    NSString* appcid = appSettings.applicationConnectionId;


// updating some of the writable settings the generic way.
// Note: this is only possible if the device is registered against SAP HANA Cloud Platform mobile services or SAP Mobile Platform Server.

    NSError* error = nil;
    NSDictionary* writableSettingsDict = [appSettings writableSettingsWithError:&error];
    // error check
    MAFApplicationSettingsProperty* property = [writableSettingsDict objectForKey:keyApplicationSettings_CustomCustom1];
    NSError* localErr = nil;
    [property setValue:@"Test" error:&localErr];
    // error check
    [appSettings updateSettings:writableSettingsDict completionBlock:^(NSError *error) {
         // error check
    }];

// Reading an application setting that has no dedicated property in the ApplicationSettings component.
    NSString* appEndPoint = [appSettings objectForKey:keyApplicationSettings_ProxyApplicationEndpoint];
Obtaining the Application Endpoint URL
This property:
  • Returns null if the device is not registered
  • Returns the URL to the service document if a Gateway connection is used
  • Returns the proxy URL, which can be used to download the service document, if the device is registered on SAP HANA Cloud Platform mobile services or SAP Mobile Platform Server
  • Is read-only
@property (nonatomic, readonly) NSURL* applicationEndpointURL;
DataVault Password Policy Property

This property returns the password policy returned by SAP HANA Cloud Platform mobile services or SAP Mobile Platform Server. If the server does not provide one, the component returns the default policy.

  • iOS N/A, use the passwordPolicy property of the LogonContext.
IReadOnlyProperty
  • The interface inherits from the IMetaProperty interface. A class that implements this interface must be constructed using a class that implements the IMetaProperty interface; properties can be created only from metadata and a value. This ensures that no ad hoc properties are created internally at runtime and that if a property is created it holds a valid value. No instances can be created that are in an inconsistent state (by holding a value that does not match the metadata restrictions defined in the metaproperty instance).
  • The interface extends the IMetaProperty interface with one Value property that holds a valid value that was validated against the metadata at construction time. After constructing the property its value and its metadata cannot be changed.
  • The application developer can access only IReadOnlyProperty instances when accessing the application settings. This ensures that application settings are not overwritten on the client side by the application developer.
Properties of this interface:
  • IsNullable Indicates whether the value of a property can be null or not. For details, see the OData specification
    @property (nonatomic, readonly, assign) BOOL isNullable;
  • Name Represents the name of one application setting. For details about restrictions and rules on naming an OData property see the OData specification. It is a read-only property:
    @property (nonatomic, readonly, copy) NSString* name;
  • Type Represents the type of the value of the property. The PropertyType type is an enumeration that defines the following constants as enum values: String, Boolean, Byte, Int8, Int16, Int32, Int64, Double, Single and Complex. An application developer can use this information to cast the generic "object" type of the "Value" property to get the typed value of a setting. When a property is a complex property (in OData terms) this "Type" property (in programming language terms) is set to Complex and the type name of the complex property is saved in the TypeName property. An application developer should check the Type and the CollectionKind properties to safely cast a property (app setting) value to a type supported by the programming language. If the CollectionKind property is set to the Collection enum value, then the value of the setting property is a read-only list of either a primitive (string, bool, int32 and so on) or a complex type. The PropertyType enumeration value might be extended by further primitive types (such as DateTime) if needed.
    @property (nonatomic, readonly, assign) MAFApplicationSettingsPropertyTypes type;
  • TypeName This property holds the OData name of the type of the property. The value is never null and is read-only.
    @property (nonatomic, readonly, copy) NSString* typeName;
IProperty
  • The class that implements this interface can be instantiated only internally by the application settings component, and the class grants write access to the setting that is stored locally. An application developer can get instances of the class that implement this interface only by calling the GetWritableSettings method. If the application developer has a reference to an instance of a class that implements this interface, the ApplicationSettings component guarantees that the Value property contains a copy of the application setting value of the original property. This means that even if the property value is set by the application developer the value is not reflected in the ApplicationSettings component thus guaranteeing a consistent and valid state of settings.
  • To modify a writable setting, the application developer must pass the read-only dictionary of <string, IProperty> instance retrieved by calling the GetWritableSettings method to the UpdateSettingsAsync method.
  • Value getter and setter methods are used: the setter method returns an NSError* instance if an error occurs when setting the value; check the return value of the setter to make sure the value is really set.

Parent topic: iOS Applications