Library capabilities

  • Determine whether the application is running on the device managed by Headwind MDM
  • Retrieve application settings from the server based on the device ID
  • Send logs to the server (the logging rules are setup on the server based on the device ID)
  • Get Push notifications sent by the server plugins

Class summary

Sample code

Integration

To integrate the library into your Android application, you need:

  1. Download the latest Headwind MDM library hmdm-1.1.6.aar on the project website and copy it to your project directory in the libs subdirectory
  2. Add the following line to your build.gradle (module level):
    implementation files('libs/hmdm-1.1.6.aar')
    (replace the version number by the latest version).
  3. Add the reference to the Headwind MDM package to the AndroidManifest.xml inside the <manifest> tag:
        <queries>
            <package android:name="com.hmdm.launcher" />
        </queries>  

HeadwindMDM

class com.hmdm.HeadwindMDM
Added in 1.1.0
This class simplifies integration with Headwind MDM and encapsulates automatic reconnection after losing connection to the service, as well as notifies your application about the configuration updates
Methods
HeadwindMDM
getInstance()
Get an instance of HeadwindMDM
int
getVersion()
Get the API version supported by the MDM app (1.1.3 = 113, or 0 for earlier versions)
void
setApiKey(String apiKey)
Set the API key, required for privileged operations like getImei() and getSerial()
void
forceConfigUpdate()
Forces reloading the configuration and installing app updates, even if the background update is disabled
boolean
connect(Context context, HeadwindMDM.EventHandler handler)
Connect to Headwind MDM service and set the event handler. This method returns true on success and false if Headwind MDM is not running.
void
disconnect(Context context)
Disconnect from Headwind MDM
boolean
isConnected()
Check the connection status. You can use the library functions if this method returns true.
String
getServerHost()
Get the host name of Headwind MDM server
String
getSecondaryServerHost()
Get the secondary host name of Headwind MDM server
String
getServerPath()
Get the path of Headwind MDM web panel
String
getServerUrl()
Get the URL of Headwind MDM server
String
getSecondaryServerUrl()
Get the secondary URL of Headwind MDM server
String
getDeviceId()
Get the device ID (number)
String
getCustom(int number)
Get the custom variable defined on the server (number can be from 1 to 3)
boolean
isManaged()
Check whether the device is in the managed mode (Device Owner is set)
boolean
isKiosk()
Check whether the device is in the kiosk mode
String
getImei()
Get the device IMEI (privileged operation, requires API key)
String
isKiosk()
Get the device serial number (privileged operation, requires API key)
boolean
setCustom(int number, String value)
Set the value of a custom variable to send it to the server
boolean
getMdmAgentError()
Get the error code if the last operation was unsuccessful, or 0 on success

HeadwindMDM.EventHandler

interface com.hmdm.HeadwindMDM.EventHandler
Added in 1.1.0
Interface for receiving events from Headwind MDM
Методы
void
onHeadwindMDMConnected()
Called when the connection is established. In this method, you can retrieve your app settings from the server.
void
onHeadwindMDMDisconnected()
Called when the connection is interrupted. This method doesn’t require any actions and it is usually followed by onHeadwindMDMConnected() within some seconds.
void
onHeadwindMDMConfigChanged()
Called when the application settings were changed on the server. In this method, you need to refresh your application settings.

MDMError

class com.hmdm.MDMError
Added in 1.0.1
Headwind MDM Error class used as an explanation class in MDMException.
Constants
int
NO_ERROR = 0
int
ERROR_NO_MDM = 1
The app is running outside Headwind MDM
int
ERROR_INTERNAL = 2
Launcher internal error
int
ERROR_GENERAL = 3
Headwind MDM library error
int
ERROR_DISCONNECTED = 4
Headwind MDM service has been disconnected
int
ERROR_INVALID_PARAMETER = 5
The method got an invalid parameter
int
ERROR_VERSION = 6
The launcher doesn’t support the API method and needs to update
int
ERROR_KEY_NOT_MATCH = 7
API key is invalid
int
ERROR_NOT_CONFIGURED = 8
Mobile agent was not yet configured at the time of an SDK call
Constructors
MDMError()
Create an empty object (code = 0)
MDMError(int code)
Initialize the error class with a specified code
Fields
int
code
Error code
Methods
static String
getMessage(int code)
Get the error message by its code
String
getMessage()
Get the error message of the class instance

MDMException

class com.hmdm.MDMException
Added in 1.0.1
Exception raised by library methods.
Constructors
MDMException(int code)
Exception with a specified code (no comment)
MDMException(int code, String comment)
Exception with a specified code and comment
Fields
MDMError
mdmError
Error code
String
comment
Additional comments

MDMPushHandler

abstract class com.hmdm.MDMPushHandler
Added in 1.0.3
Helper class allowing the mobile application to receive Push messages sent by server plugins. This is the abstract class which must be subclassed in your application.
Methods
abstract void
onMessageReceived(MDMPushMessage message)
Called when a Push message is received
void
register(String messageType, Context context)
Registers a handler waiting for messages of a specified type
void
register(String[] messageTypes, Context context)
Registers a handler waiting for messages of multiple specified types
void
unregister(Context context)
Unregisters a handler

MDMPushMessage

class com.hmdm.MDMPushMessage
Added in 1.0.3
Push message delivered to the application by a server plugin.
Constants
String
MessageConfigUpdated
The built-in message type sent when Headwind MDM configuration is updated on the server
Methods
String
getType()
Gets a message type
void
setType(String type)
Sets a message type
org.json.JSONObject
getData()
Gets a payload
void
setData(org.json.JSONObject data)
Sets a payload

MDMService

class com.hmdm.MDMService
Added in 1.0.1
Main class used to connect the mobile app to Headwind MDM service.
Constants
String
KEY_SERVER_HOST
Query the server host name (including the protocol)
String
KEY_SECONDARY_SERVER_HOST
Query the server host name (including the protocol)
String
KEY_SERVER_PATH
Query the path of the server control panel (empty if deployed at root path)
String
KEY_DEVICE_ID
Query the device ID
Methods
MDMService
getInstance()
Get the instance of the MDMService object
int
getVersion()
Get the API version supported by the MDM app (1.1.3 = 113, or 0 for earlier versions)
void
forceConfigUpdate()
Forces reloading the configuration and installing app updates, even if the background update is disabled
boolean
connect(Context context, MDMService.ResultHandler handler)
Connect to the Headwind MDM service and notify the handler about the connection result. Returns true on success and false on error (usually when the application is running outside Headwind MDM)
Bundle
queryConfig() throws MDMException
Get the server configuration (to retrieve the configuration parameters, get one of the KEY_… constants from the resulting bundle)
Bundle
queryConfig(String apiKey) throws MDMException
Get the server configuration including privileged values (to retrieve the configuration parameters, get one of the KEY_… constants from the resulting bundle)
void
setCustom(int number, String value) throws MDMException
Set the value of a custom variable to send it to the server

MDMService.ResultHandler

interface com.hmdm.MDMService.ResultHandler
Added in 1.0.1
Interface receiving the result of connection to Headwind MDM service.
Methods
void
onMDMConnected()
Called when the connection is successful
void
onMDMDisconnected()
Called when the service is disconnected (usually when Headwind MDM launcher is updated or crashed). It is recommended to reconnect to Headwind MDM within some seconds after receiving this signal.

MDMService.Log

static class com.hmdm.MDMService.Log
Added in 1.0.1
The class sending application logs to the server. This class has the interface similar to android.util.Log, so you can easily replace the logging engine without reviewing and updating the whole code.
Constants
int
ERROR = 1
int
WARN = 2
int
INFO = 3
int
DEBUG = 4
int
VERBOSE = 5
Methods
void
log(int level, String tag, String message)
Sends a log message to the server
void
v(String tag, String message)
void
d(String tag, String message)
void
i(String tag, String message)
void
w(String tag, String message)
void
e(String tag, String message)
These methods are similar to android.util.Log. They combine writing to Android internal log (logcat) and sending the log message to the server.

MDMService.Preferences

static class com.hmdm.MDMService.Preferences
Added in 1.0.4
This class is used to retrieve app references from the server (group or bulk Android app configuration). The feature of storing app preferences on the server is not yet implemented.
Methods
String
get(String attr, String defValue)
Gets an attribute defined in “Application settings” tab of the configuration.
boolean
set(String attr, String value)
Sets an attribute (not yet implemented)
void
apply()
Forces uploading the attributes to the server (not yet implemented)

Sample code

Version 1.1.0 and above

To include Headwind MDM functions in your application, use the following code sample:

public class MainActivity extends AppCompatActivity implements HeadwindMDM.EventHandler {
    ...
    private HeadwindMDM headwindMDM;
 
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ...
        headwindMDM = HeadwindMDM.getInstance();
    }
 
    @Override
    protected void onResume() {
        super.onResume();
        ...
        if (!headwindMDM.isConnected()) {
            if (!headwindMDM.connect(this, this)) {
                // Your application is running outside Headwind MDM
            }
        } else {
            // Already connected, but settings may have changed
            // when our app was in the background, so reload them
            loadSettings();
        }
    }
 
    @Override
    protected void onDestroy() {
        headwindMDM.disconnect(this);
        super.onDestroy();
    }
 
    @Override
    public void onHeadwindMDMConnected() {
        // Connected to Headwind MDM, now you can load settings and use other MDM functions
        loadSettings();
    }
 
    @Override
    public void onHeadwindMDMDisconnected() {
    }
 
    @Override
    public void onHeadwindMDMConfigChanged() {
        // Settings were changed on the server, you need to reload them
        loadSettings();
    }

    // Get the application settings from the server
    private void loadSettings() {
        String someSetting = MDMService.Preferences.get("some_setting", getString(R.string.default_setting));
    }
}

Versions prior to 1.1.0

If you’re using a legacy version, you need to implement the reconnection after the connection interruption (for example after the update of Headwind MDM launcher).

To include Headwind MDM functions in your application, use the following code sample:

public class MainActivity extends AppCompatActivity implements MDMService.ResultHandler {
    ...
    private MDMService mdmService;
    private boolean mdmConnected = false;
 
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ...
        mdmService = MDMService.getInstance();
    }
 
    @Override
    protected void onResume() {
        super.onResume();
        ...
        if (mdmConnected) {
            // If we're already connected to Headwind MDM, load MDM settings and do other MDM related stuff here
            String someSetting = MDMService.Preferences.get("some_setting", getString(R.string.default_setting));
        } else {
            if (!mdmService.connect(this, this)) {
                // Failed to connect to Headwind MDM because the app is running outside MDM
            }
        }
    }
 
    @Override
    public void onMDMConnected() {
        mdmConnected = true;
        // Connected to Headwind MDM, now we can do MDM related stuff
        String someSetting = MDMService.Preferences.get("some_setting", getString(R.string.default_setting));
    }
 
    @Override
    public void onMDMDisconnected() {
        mdmConnected = false;
        // Reconnect in 5 sec (this could be after update or crash of Headwind MDM!)
        new Handler().postDelayed(new MDMReconnectRunnable(), 5000);
    }
 
    public class MDMReconnectRunnable implements Runnable {
        @Override
        public void run() {
            if (!mdmService.connect(MainActivity.this, MainActivity.this)) {
                // Retry in 1 minute
                new Handler().postDelayed(this, 60000);
            }
        }
    }
}