LifeLine Software Development Kit User Guide

4.1.2

LenovoEMC Confidential
LenovoEMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. WARNING: THE INFORMATION CONTAINED HEREIN HAS NO WARRANTY. LENOVO EMC, LTD. AND THEIR AFFILIATES MAKE NO WARRANTIES EXPRESS OR IMPLIED CONCERNING ANY INFORMATION PROVIDED HEREIN. THIS DOCUMENT AND ALL OF ITS CONTENTS ARE PROVIDED ON AN AS IS BASIS. THE USER ASSUMES ANY RISK OF LOSS INCLUDING ANY LOSS OF DATA, AND AGREES TO WAIVE ANY CLAIM FOR DAMAGES ASSOCIATED WITH THE INFORMATION HEREIN. PLEASE DO NOT USE THIS DOCUMENT OR THE INFORMATION CONTAINED HEREIN IF YOU DO NOT AGREE. BY PROCEEDING TO USE THIS DOCUMENT OR ANY INFORMATION HEREIN, YOU AGREE TO WAIVE ANY AND ALL CLAIMS FOR DAMAGES, INCLUDING DIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL, AND LOST PROFIT DAMAGES.

Use, copying, and distribution of any LenovoEMC software described in this publication requires an applicable software license.

Copyright 2013 LenovoEMC, Ltd. All rights reserved. LenovoEMC and LifeLine are trademarks of LenovoEMC, Ltd. in the United States, other countries, or both. Lenovo and the Lenovo logo are registered trademarks of Lenovo in the United States, other countries, or both. The EMC logo is a registered trademark of EMC Corporation in the United States and/or other countries. Certain other product names, brand names, and company names may be trademarks or designations of their respective owners.

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

Revision History Date

5/4/11 5/9/11 5/13/11 7/8/11 7/21/11 10/26/11 12/11/11 01/16/12 01/20/12 01/23/12 02/07/12 6/13/12 07/20/12 9/26/12 12/12/12 1/18/13 1/31/13 3/1/13 3.1.10 3.1.10 3.2.3 3.3.2 3.3.2 3.3.2 3.3.2 3.3.2 3.3.4 3.3.4 3.4.2 3.4.4 4.0.2 4.0.2 4.0.2

Version Change Summary

3.1 Added Best Practices Section Added audience and prerequisites section Application set upgrade edits Events updates Added "lifelineParser" flag and sessions Minor fix to section 2.2 Updates to XML descriptions in sections 6, 10, 14, 16 and 19 Included requirements for "setup" category Included support for new REST APIs Updates to application.xml description and API call examples Added new supported devices Updates to application an application set attributes Updated toolchain information Changes to sections 6,10, 12.2 and 14 Changes to sections 6, 8, 12, 13 and 15 Added section 12.10 Added section 12.11. Updated sections 6 and 12.1.2

3/11/13 7/31/13

4.0.2 4.1.2

Updates Updates to sections 2, 3, 6, 10, 12.9, 13.5, 14, 15. Added sections 12.13, 12.14, 12.15, 12.16

Page 2 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

Table of Contents
1 1.1 2 2.1 2.2 2.3 2.3.1 2.3.2 3 3.1 3.2 3.3 3.4 4 5 5.1 5.2 5.3 5.4 5.5 5.6 5.7 5.8 6 6.1 6.2 6.2.1 6.2.2 6.3 6.3.1 6.4 7 8 Preface................................................................................................................................................... 7 Intended Audience and Development Prerequisites ....................................................................... 7 Introduction .......................................................................................................................................... 7 SDK Terminology ............................................................................................................................ 7 Supported Architectures.................................................................................................................. 8 LifeLine SDK Features .................................................................................................................... 8 Applications .............................................................................................................................. 9 Libraries ................................................................................................................................... 9

Getting Started ..................................................................................................................................... 9 LifeLine SDK System Requirements ............................................................................................. 10 Installing the LifeLine SDK ............................................................................................................ 10 Installed Components ................................................................................................................... 11 Checking Your LifeLine SDK Installation ...................................................................................... 11 LifeLine API Reference ...................................................................................................................... 11 Application Creation Overview ......................................................................................................... 12 Your Applications with LifeLine Applications................................................................................. 12 Use the o2 Tool for an Application Template ................................................................................ 12 Write Your Code ............................................................................................................................ 12 Design a User Interface for Your Application ................................................................................ 12 Build Your Application ................................................................................................................... 12 Create an Application Set ............................................................................................................. 13 Build Your Application Set ............................................................................................................ 13 Test Your Application .................................................................................................................... 13 Creating a LifeLine Application ........................................................................................................ 13 Using the o2 Tool .......................................................................................................................... 13 Modifying the Application.xml File ................................................................................................. 13 Application File Example ....................................................................................................... 14 Application Parameters .......................................................................................................... 15 Supported categories .................................................................................................................... 18 Setup category ....................................................................................................................... 19 Interaction between executable file and Application Manager...................................................... 19 Writing Your Code .............................................................................................................................. 20 Designing a User Interface ................................................................................................................ 20

Page 3 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd. 8.1.1 8.1.2 8.1.3 9 10 10.1 10.2 10.3 11 11.1 11.2 12 12.1 12.1.1 12.1.2 12.2 12.3 12.3.1 12.3.2 12.3.3 12.3.4 12.3.5 12.4 12.5 12.6 12.6.1 12.6.2 12.6.3 12.6.4 12.7 12.8 12.8.1 12.8.2 12.9 12.10 12.11 12.12

CONFIDENTIAL AND PROPRIETARY

Application Localization ......................................................................................................... 21 LifeLine Parser ....................................................................................................................... 21 Session Flags ........................................................................................................................ 22

Building Your Application ................................................................................................................. 22 Creating an Application Set ........................................................................................................... 22 Modifying the <application set id>.xml File ............................................................................... 23 Application Set Parameters ....................................................................................................... 23 Building Your Application Set .................................................................................................... 24 Testing Your Applications ............................................................................................................. 24 Setting up the LifeLine VM ........................................................................................................ 25 Login Credentials with Security Enabled ................................................................................... 25 Designing More Advanced Applications ...................................................................................... 25 Interprocess Communication Between LifeLine and SDK Applications .................................... 26 Third-party Application functions ........................................................................................... 26 Library for the Inter Process Communication (IPC) Mechanism ........................................... 26 Events ........................................................................................................................................ 29 Redirection APIs ........................................................................................................................ 30 Selective Redirection ............................................................................................................. 31 Global Redirection ................................................................................................................. 31 Stopping Redirection ............................................................................................................. 31 Homepage Redirection .......................................................................................................... 31 Redirection sample ................................................................................................................ 32 Custom home page ................................................................................................................... 32 Linux Kernel Module Development ........................................................................................... 32 Exposing New REST APIs ........................................................................................................ 32 sdkapi.xml definition............................................................................................................... 32 SDK API parameters.............................................................................................................. 34 Registering DBus Callbacks .................................................................................................. 35 Incoming data ........................................................................................................................ 35 Registering callbacks for LifeLine REST APIs .......................................................................... 36 Deferred Schedule..................................................................................................................... 37 Registering a Schedule .......................................................................................................... 37 Deregistering a Schedule ...................................................................................................... 37 Custom apache module ............................................................................................................ 38 Calling LifeLine API from the backend ...................................................................................... 39 Web server proxy configuration ................................................................................................. 39 Email notifications...................................................................................................................... 40

Page 4 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd. 12.13 12.13.1 12.13.2 12.13.3 12.14 12.15 12.16 13 13.1 13.2 13.3 13.4 13.5 13.6 13.7 14 14.1 14.1.1 14.2 14.2.1 14.2.2 14.2.3 14.3 14.3.1 15 15.1 15.2 15.3 16 17 18 19 20 20.1 20.2 20.3 20.3.1

CONFIDENTIAL AND PROPRIETARY

Video output support ................................................................................................................. 40 Compiling SDK applications with QT support .................................................................... 41 API interaction .................................................................................................................... 41 Additional configurations .................................................................................................... 42 User Visible Logs....................................................................................................................... 42 Storing Application Data ............................................................................................................ 42 Custom validation during installation ......................................................................................... 43 Application Best Practices ............................................................................................................ 43 Verify a Service or Feature Is Running Before Using It ............................................................ 43 No Share Creation Until a User Launches an Application ........................................................ 43 Control Running State of the Application on the Applications Home Page .............................. 44 Check Firmware Version for Compatibility ................................................................................ 44 Store Application Data and User Metadata in the ApplicationData Share ................................ 44 When to Use Callbacks for LifeLine APIs ................................................................................. 45 Combining Configuration Parameters for the Applications Executable .................................... 45 Upgrading an Application .............................................................................................................. 46 Upgrade Info XML File .............................................................................................................. 46 Parameter Explanations ........................................................................................................ 46 Manual Upgrade ........................................................................................................................ 49 Including the Upgrade Information File in the TGZ File ......................................................... 49 Upgrading through the UI ...................................................................................................... 49 Upgrade through the REST APIs ........................................................................................... 50 Automatic Upgrade .................................................................................................................... 51 Automatic Upgrade Procedure .............................................................................................. 51 Migration from Previous Versions of the LifeLine SDK .............................................................. 52 Migrating to Version 4.1 from Any Version Before 4.0 .............................................................. 53 Migrating to Version 4.1 from Any Version Before 3.2 .............................................................. 54 Migrating to version 4.1 from versions 3.2 and 3.3 ................................................................... 55 Deleting Applications during an Upgrade .................................................................................... 55 Debugging Applications ................................................................................................................ 55 Recommended Testing Tools ....................................................................................................... 55 Getting Help .................................................................................................................................... 55 Appendix A Sample Code .............................................................................................................. 56 REST and XMLRPC Examples ................................................................................................. 56 REST Call with No Parameters ................................................................................................. 56 REST Call with Parameters ....................................................................................................... 57 Shares API ............................................................................................................................. 57

Page 5 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd. 20.3.2 20.3.3 20.4 20.5 20.6 20.7 20.8 20.9 20.10 20.11 21 21.1 22

CONFIDENTIAL AND PROPRIETARY

SecurityEnable API ................................................................................................................ 58 UserCreate API ...................................................................................................................... 58 REST Call with Struct as a Parameter ...................................................................................... 58 Error Information........................................................................................................................ 58 To Call Methods Using XML-RPC ............................................................................................. 58 Example XML-RPC call with No Parameters ............................................................................ 59 Example XML-RPC call with Parameters .................................................................................. 59 Example XML-RPC call with Struct as a Parameter ................................................................. 59 Error Information........................................................................................................................ 59 Sample Applications .................................................................................................................. 59 Appendix B SDK Utilities ............................................................................................................... 60 SDK Application Utility Program ................................................................................................ 60 Appendix C Installing Partners Applications at Manufacturing ................................................ 60

Page 6 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

1 Preface
Welcome to the Software Developer's Guide for LifeLine. In this guide, you will find the information you need to use the Software Development Kit (SDK) that LifeLine provides. This guide contains information on the tools and APIs provided to help you create applications for LifeLine.

1.1

Intended Audience and Development Prerequisites

The LifeLine SDK is intended for use by experienced developers. At a minimum, developers should have the following knowledge before creating applications with the LifeLine SDK: Basic understanding of Linux environments and Linux system programming. Knowledge of C, XML, and Python programming/scripting and data structures. Ability to administer VMware desktop and ESX. Understanding of network storage concepts, including TCP/IP, NFS, CIFS, iSCSI, VLANs, Jumbo Frames, Link aggregation, and port bonding. Knowledge of REST, XMLRPC, and NAS. User interface development experience.

2 Introduction
The LifeLine SDK is a software development kit that contains a collection of tools, application programming interfaces (APIs), sample applications, and documentation. It is used to build custom applications that access LifeLine functionality.

2.1

SDK Terminology
There are several terms you should know to become familiar with the LifeLine SDK. LifeLine: The LenovoEMC Original Equipment Manufacturer (OEM) storage platform software used in LenovoEMC devices. o2: (O2) Oxygen SDK command line utility. Application Set: A single file that contains one or more applications to be loaded onto a LenovoEMC device running LifeLine.

Page 7 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

2.2

Supported Architectures
The LifeLine SDK supports various computer processor architectures, and each can be used for compiling applications so they execute optimally on different LifeLine devices.

SDK compilation target i686-vmware arm-ix2-ng

Target LifeLine Device Virtual Machine (VM) ix2 ix2-dl

Supported CPU Architecture x86 (32 bit) ARMv5tel (32 bit)

Toolchain Directory gcc-4.7.2-glibc-2.13i686 gcc-4.6.3-eglibc2.13-arm-eabi

arm-hm3 h4c x86_64-px

Lenovo EZ ix4-300d px4-300d px6-300d x86_64 (64 bit) gcc-4.7.2-glibc-2.13x86_64

b4b

px4-400d px4-400r

b2a x86_64-ix

px2-300d ix12-300r px12 350r

px4-300r px12-450r r12b

px4-300r px12-400r px12-450r

2.3

LifeLine SDK Features

The LifeLine SDK includes the following features: GNU toolchain and other tools for the supported architectures LifeLine binary libraries LifeLine device simulator (VM) Hardware-independent development Application template and application creation scripts Easy-to-use advanced storage, security, and content sharing LifeLine RPC and XMLPRC API documentation in Doxygen format Upgrades of multiple versions of a third-party application Installation of application icons Runtime updates and installations of applications written for LifeLine Automatic software updates Remote Procedure Call (RPC), Representational State Transfer (REST), and XML-RPC support

Page 8 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

2.3.1 Applications
The LifeLine SDK includes example applications written in C. These applications are available in the $LLSDK_HOME/samples/ directory.

2.3.2 Libraries
The LifeLine SDK includes a set of open source libraries that are useful in application development, and SDK developers have an open license to use these libraries. Some of the core libraries are listed below: DBus (Desktop Bus) DBus is a daemon running in the system that controls application communication. All applications that need to communicate with each other on DBus connect to the daemon first. GLib GLib is a general utility library used as the lowest layer of the GTK+ graphical user interface software stack. GLib attempts to abstract most of the operating systems functions allowing GTK+ to run on Linux, Mac (using XWindows), and Windows. SQLite SQLite is a relational database engine available to all applications written for LifeLine.

3 Getting Started
The first step towards using the LifeLine SDK is to install it. The LifeLine SDK is available for download from http://developer.lifelineapps.com. You must first register as a user and create an account before you can access the download site. The LifeLine SDK is composed of seven separate packages, that can be downloaded according to your specific needs: LifeLine-SDK-<version>.tar.bz2 The base package for the SDK, containing all the scripts (o2 tool, build scripts, SDK installation script), SDK sample applications, SDK documentation, REST API documentation and licenses. This package is mandatory to be able to write and compile your own SDK applications. LifeLine-SDK-ARM-<version>.tar.bz2 - package containing the platform-specific versions of the libraries and header files used by the LifeLine SDK for ARM-based devices. LifeLine-SDK-ARM-Kernel-<version>.tar.bz2 - package containing the kernel source files for ARM-based devices. LifeLine-SDK-Intel-<version>.tar.bz2 - package containing the platform-specific versions of the libraries and header files used by the LifeLine SDK for Intel-based devices. LifeLine-SDK-Intel-Kernel-<version>.tar.bz2 - package containing the kernel source files for Intel-based devices. LifeLine-SDK-Toolchain-<version>.tar.bz2 package containing the toolchains used by the LifeLine SDK for all device models. This package is mandatory to be able to write and compile your own SDK applications. LifeLine-SDK-VM-<version>.tar.bz2 package containing the latest LifeLine virtual machine and its platform-specific libraries, header files and kernel source files used by the LifeLine SDK. This package is only needed to compile and test SDK applications without using real LifeLine devices. After downloading the required packages of the LifeLine SDK, you install them on your development machine. There is a dependency tree among these packages. During the installation procedure, the LifeLine SDK will validate that the versions of the downloaded packages are all compatible. If an update is released for one or more of these packages, you may download only the necessary packages and run the installation script again, passing only the new packages, to install them and verify that theyre still compatible with the packages that were not updated.

Page 9 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

When any application is built using the LifeLine SDK, these dependencies are also validated to make sure that the generated installation package is actually compatible with the target version of the LifeLine firmware.

3.1

LifeLine SDK System Requirements

Before installing the LifeLine SDK, be sure your development machine meets these minimum requirements: Linux system with 2.6 kernel or later Python 2.7 or later installed GNU Make installed GNU C Library (glibc)2.11 or later

3.2

Installing the LifeLine SDK

To install the LifeLine SDK, perform the following procedure: 1. Unpack the LifeLine-SDK-<version>.tar.bz2 package to a desired location on your development machine. 2. Run the installsdk.py script, passing as parameters the required packages: -a <arm package> -l <arm kernel source package> -i <intel package> -k <intel kernel source package> -t <toolchain package> -v <virtual machine package> 3. Define the environment variable LLSDK_HOME on your development machine to contain the directory where LifeLine is installed. For example: $ export LLSDK_HOME=$HOME/LifeLine-SDK-X.X.X.XXXXX 4. Add ${LLSDK_HOME}/bin to the beginning of the PATH environment variable on your development machine: $ export PATH=$LLSDK_HOME/bin:$PATH

Page 10 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

3.3

Installed Components
After installing the LifeLine SDK, the following components are available: Compiler toolchains Libraries and header files for each of the supported architectures Application management scripts, such as o2. Sample applications Documentation

3.4

Checking Your LifeLine SDK Installation

The recommended way to test your LifeLine SDK installation is to try compiling the sample applications. 1. In the SDK installation directory, change to the SDK samples directory. cd $LLSDK_HOME/sdksamples 2. Create an application set for one of the supported architectures with the command: make target=architecture For example, make target=i686-vmware.

4 LifeLine API Reference

LifeLine APIs are used to let your application communicate with LifeLine. LifeLine APIs can be used with XML Remote Procedure Call (XMLRPC) and Representational State Transfer (REST)/JavaScript Object Notation (JSON). Both XMLRPC and REST/JSON are provided as a simple means to perform RPC calls to a LenovoEMC device from external entities. The REST API provides a method for accessing the API functions defined by the XMLRPC interface. Requests are submitted by GET or POST commands with arguments specified in the standard tag=value form. Arguments can be included in the URL as arguments or in POST content. The response is formatted as JSON data that can be used directly by JavaScript running in the browser. This format is much simpler for a web page to manipulate. XMLRPC provides a simple set of base types and a definition for a common transfer structure that is implemented in a large number of generally available tools. By using XMLRPC, it becomes very simple to perform scripted operations using tools such as Python, which has a very clean interface to XMLRPC. Complete documentation about the LifeLine APIs is available in html format and is included with the LifeLine SDK. The documentation is available under $LLSDK_HOME/doc/sdk.html.

Page 11 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

5 Application Creation Overview

Creating applications with the LifeLine SDK is a seven-step process.

5.1

Your Applications with LifeLine Applications

The following diagram shows where your applications reside in the LifeLine platform.

5.2

Use the o2 Tool for an Application Template

You start creating applications using the LifeLine o2 command line utility. The o2 utility provides a project template, and it creates an application directory where you place all your application content.

5.3

Write Your Code

Add your application code to the application directory created by o2.

5.4

Design a User Interface for Your Application

Your applications can have their own web user interface by using the UI tools provided by Apache.

5.5

Build Your Application

You use the make file (which is created by o2) located in the application directory to build your application for different supported architectures.

Page 12 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

5.6

Create an Application Set

You use the LifeLine o2 command line utility to create an application set, which will contain your application. The o2 utility creates an application set directory, containing a template.

5.7

Build Your Application Set

You use the make file (which is created by o2) located in the application set directory to build your application set for different supported architectures.

5.8

Test Your Application

You can install your application set and test your application on a virtual machine or some other NAS device.

6 Creating a LifeLine Application

You create applications in any directory on the development machine that has the installed LifeLine SDK.

6.1

Using the o2 Tool

1. To create an application, enter the following commands in a shell prompt to begin creating your application: o2 create <app-id> <vendor-name> For example, o2 create sampleAppIdentity companyXYZ This command creates an application directory with the same name as the application that you specified, for example, sampleAppIdentity. <app-id> supports alphabetic characters only. <vendor-name> supports alphabetic and numeric characters only. Note that the <app-id> must be unique within a specific <vendor-name> 2. Change to the application directory created by the previous step. For example, cd sampleAppIdentity The application directory contains the following files: application.xml: This file defines static application information and constant values about the application. main.c: This is a template file for your source code. Makefile: The utility that builds your SDK application. sdkapi.xml: This file defines the REST APIs exposed by the application.

6.2

Modifying the Application.xml File

To update your application, you modify the application.xml file, which is in the application directory.

Page 13 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

6.2.1 Application File Example

The following is an example of an XML file that is created every time you create a new application. <application id="sampleAppIdentity" displayName="Sample Application" version="1.0" icon="application.png" smallicon="application-small.png" vendor="companyXYZ" Keywords="sample" setupFunc="sampleSetupFunc" authenticateFunc="sampleAutheticateFunc" wwwDir="1" cgibinDir="0" decodeUrlParameters="0" lifelineParser="1" custommodule=1 proxy=1 applicationdata=1 keywords="Individual words to use in searches to match this icon separated by spaces" _gettext_="displayName,keywords"> <uri Text="applicationPage.html"/> <description Text="Summary text for hover and setup page" _gettext_="Text "/> <category id="common"/> <category id="system"/> <category id="setup"/> <setup sequence="20"> <uri Text="scripts/sampleAppSetup.js"/> </setup> <executable command="executable" restartOnReboot="1" memSize="10000" /> <webserver> <custommodule path="module.so" module="custom_module" handler="exampleHandler" www="1" cgibin="0"/> <proxy location="/sampleProxy" http="8080" https="4443"/> </webserver> <!The following is optional and required for localization strings only--> <Localization> <Text msgid="To reset the device press the small recessed button on the back."> <Locale Id="de">

Page 14 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

<msgstr>Um das Gert zurckzusetzen, drcken Sie die kleine vertiefte Taste auf der Rckseite.</msgstr> </Locale> <Locale Id="es"> <msgstr>Para restablecer el dispositivo, presione el pequeo botn empotrado que se encuentra en la parte posterior.</msgstr> </Locale> </Text> <Text msgid="General Error!" lognumber=17> <Locale Id="de"> <msgstr>Allgemeiner Fehler!</msgstr> </Locale> <Locale Id="es"> <msgstr>Error general!</msgstr> </Locale> </Text> </Localization> </application>

6.2.2 Application Parameters

When you create your application, you modify parameters that are in the application.xml file. The following table lists the modifiable parameters and their definitions.

Application Parameter <application/_gettext_>

Definition Localization information. The value defined here points to the attributes that are going to be localized, using the strings defined in the Localization element. Any function that an application can call during the authentication process. This is an optional parameter and is called by LifeLine over DBus. If 1 then cgibinDir directives are created in the Apache.conf file so that it can be accessed by the web. The application access URL will be <http://<ip-address>/apps/<vendor>/<app-id>/cgibin/ If 1, the Apache server is configured to decode the characters in the "QUERY_STRING" part of the URLs for incoming CGI requests, before setting up the environment variables for the request and invoking the CGI script. A 50-pixel x 50-pixel image file that must be

<application/authenticateFunc>

<application/cgibinDir>

<application/decodeUrlParameters>

<application/icon>

Page 15 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY provided so it appears in the UI. The path must be relative to the applications www directory.

<application/smallicon>

A 32-pixel x 32-pixel image file that must be provided so it appears in the UI. The path must be relative to the applications www directory. A unique identifier for an application, which supports alpha characters only. No two applications can have the same ID within the same vendor. A localized space-separated list of keywords that is used in the feature search. If no keyword is specified, the search never finds this application. The application name. It can be localized. Any function that an application can call during the initial setup sequence. This is an optional parameter and is called by LifeLine over DBus. Application vendor name. This name is also in the application set configuration file. The application version. If 1, then www directives are created in the Apache.conf file so that it can be accessed by the UI. The application access URL is <http://<ip-address>/apps/<vendor>/<app-id>/ If 1, then all html pages in the applications www directory will pass through the LifeLine Parser when they are accessed by the UI. For more information on the LifeLine parser, refer to sections 8.1.2 and 8.1.3. Defines whether the icon for the application is visible in the LifeLine UI. If 1, no icon is displayed for this application. Defines whether the application contains a custom Apache module. If 1, the custom module definition must be present in the <webserver/custommodule> tag. Defines whether the application requires a proxy configuration to be made to redirect all incoming requests to a custom web server If 1, the proxy configuration parameters must be present in the <webserver/proxy> tag.

<application/id>

<application/keywords>

<application/displayName> <application/setupFunc>

<application/vendor> <application/version> <application/wwwDir>

<application/lifelineParser>

<application/hidden>

<application/custommodule>

<application/proxy>

<application/applicationdata>

Defines whether the application requires a folder to be created in the ApplicationData share to store its application data. If 1, the path to the new folder will be passed on as the second argument to the executable of the application.

<category/id>

The category in which the application is a member. Multiple categories are allowed, and the application

Page 16 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY icon is available in the Web UI for each category specified. Supported id values are listed in Section 6.3.

<description/_gettext_>

Localization information for description. The value defined here points to the attributes that are going to be localized, using the strings defined in the Localization element. Description of the application. Displayed like ToolTip text. A page that opens when the application icon is clicked. The path must be relative to the applications www directory. This page always opens in a new browser window.

<description/Text> <uri/Text>

<executable/command>

An executable command that is started by the LifeLine Application Manager according to the additional configuration values. Do not daemonize this executable file. Refer to section 6.4 for details on the interaction of the LifeLine Application Manager with the executable file.

<executable/days> <executable/memSize> <executable/minutes> <executable/restartOnReboot> <executable/runOnce>

Schedules the executable to run the specified number of days. Identifies the maximum memory allowed for this executable. Schedules the executable to run the specified number of minutes. Identifies if the executable is restarted after reboot. If set to 1, the executable runs only once. Otherwise, the executable is called again soon after it ends. If set to 1, the executable will run for the amount of time specified by the values for the days and minutes parameters. Set the priority that is used to run this executable, according to the usual process priority settings used in Unix-like systems. Used to configure the entry for the application in the "Setup" page. This element is only required when the application is added to the "setup" category. This parameter specifies the position of the application icon on the Setup page. A JavaScript file that is called when the setup page is loaded. The path must be relative to the applications www directory. For example: scripts/file.js

<executable/scheduled>

<executable/nice>

<setup>

<setup/sequence> <setup/uri/Text>

Page 17 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

Refer to section 6.3.1 for details about the required contents of this file. <webserver/custommodule/path> A custom apache module used to handle incoming HTTP requests directed at the applications URLs. The path must be relative to the applications base directory. Refer to section 12.9 for more details about this feature. <webserver/custommodule/module> <webserver/custommodule/handler> <webserver/custommodule/www> The name of the external variable of type module defined in the source code of the custom module. The name of the actual handler declared in the .so file. Specifies whether the custom module should handle requests directed at the URLs of the applications www directory. Specifies whether the custom module should handle requests directed at the URLs of the applications cgi-bin directory. The location to be used for the proxy configuration. Refer to section 12.11 for details about this feature <webserver/proxy/http> <webserver/proxy/https> <Localization> Specifies which port number should be used for the HTTP traffic that is redirected by the proxy. Specifies which port number should be used for the HTTPS traffic that is redirected by the proxy. Used to configure translatable strings that can be used for translating any user-visible text for the application, such as the "description" and "keywords" attributes from the application.xml file or any text in the html pages of the application. The original text that will be translated. All occurrences of the text in the UI must be an exact match with this string. The log number of a message that will be used as a user-visible log in the Event Log. This number must be unique for each vendor. The language code for the translated text. Can be one of the values defined in section 8.1.1. The actual translated text.

<webserver/custommodule/cgibin>

<webserver/proxy/location>

<Localization/Text/msgid>

<Localization/Text/lognumber

<Localization/Text/Locale/Id> <Localization/Text/Locale/msgstr>

6.3

Supported categories
The supported categories for displaying your application in the LifeLine Web UI are common, cloud, system, backup, media, storage, network, surveillance, and setup. Your application can be included in as many categories as suitable, but it should be included in at least one specific category other than "common".

Page 18 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

6.3.1 Setup category

To include your application in the setup category, the "setup" tag, together with all its attributes and child elements, becomes mandatory for the application.xml file. The JavaScript file referenced by the <setup/uri/Text> must contain at least two functions: <vendor_id>_<application_id>load(): This function must display the current status of the application. The status in the form of a string must be set into a DOM element of the current page with id "<vendor_id>_<application_id>setup. status". This can be done with the following jQuery command:

$("#<vendor_id>_<application_id>setup .status").text(<status>); E.g: $(#companyXYZ_sampleAppIdentitysetup .status).text(Sample application is installed.) Since this function is invoked by LifeLine's setup page, it is not necessary to include the jQuery library in your application just for this.

<vendor_id>_<application_id>launch(): This function must open the application's configuration page in a new window. Since this function is invoked by LifeLine's setup page, it is necessary to include the relative path to the html page, such as:

../apps/<vendor>/<app-id>/<pagename>.html

Refer to the "setuppageapp" sample SDK application for examples of how to perform these steps.

6.4

Interaction between executable file and Application Manager

The executable file of an SDK application is the main interaction point between LifeLine and the application. The application must correctly set the additional configuration parameters to achieve the desired behavior for the executable: restartOnReboot: when this attribute is enabled, the executable is always started by the Application Manager when the device is restarted. One special case of this behavior is that the executable is also started immediately after the application is installed. If this attribute is disabled, the executable is not started by the Application Manager when the application is installed. runOnce: when this attribute is enabled, the executable is never automatically restarted by the Application Manager. Otherwise, the executable is automatically restarted by the Application Manager in case it completes execution normally or exits with error. Only if the executable is explicitly stopped by a call to the ApplicationRun API, it is not restarted automatically.

Independent of the behavior imposed by the two flags above, an executable file must be running to handle incoming calls to any of the backend functions registered for the REST API exposed by the SDK application. To help with that, whenever a REST API is called, the executable is automatically started by the Application Manager (in case it is not running already) and, shortly after that, the respective registered function is called via Dbus.

Page 19 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

Because of that, whenever an executable is started by the Application Manager, it must remain running at least for a few seconds to allow it to receive the incoming Dbus calls. It is not necessary, however, to keep the executable locked in a running state forever just to handle incoming Dbus calls. This is usually done using an infinite loop and should be avoided. Refer to the SDK API Test sdk sample for a simple keep-alive mechanism that allows the executable to receive incoming Dbus calls without having to keep it locked in an infinite loop. The restartOnReboot and runOnce parameters are enabled by default, which allows the Application Manager to start your application executable automatically when your storage device starts. When the executable starts, it runs initialization steps that allow your SDK application to work. Those initialization steps may include: Receive the path to the automatically created share to store application data Register backend functions for the REST APIs exposed by the SDK application (refer to section 12.6 for details) Register APIs to be notified of LifeLine events (refer to section 12.2 for details) Register callbacks for LifeLine APIs (refer to section 12.7 for details)

Enabling restartOnReboot and disabling runOnce is not recommended, particularly if the executable file has a very short life cycle. In this case, the executable completes quickly and is continuously restarted by the Application Manager when the storage device restarts. This can consume system resources and affect system operating performance. It should be avoided.

7 Writing Your Code

An application for LifeLine can be written in any language, and every application runs in its own Linux process. Refer to the main.c file. Also refer to the API documentation for information on writing applications for LifeLine. Your SDK application should make no assumptions about the current working directory when it is executed. One of the first actions your application must take is to change the working directory on your system to be the one that contains the application executable. You can change the working directory by m aking the following call at the beginning of each applications main function: chdir(dirname(argv[0])); If your application doesnt change the working directory, then the LifeLine stack cannot communicate with other SDK applications. When the application is uninstalled from the storage device, the working directory and all its contents are removed. To store permanent data and files on the storage device, the application should use the ApplicationData share as described in section 12.15.

8 Designing a User Interface

You can design a user interface, and save your UI-related files, as either HTML or CGI. At runtime, these UI-related files are accessed by the Web server virtual directory. All static files that should be accessible through the Web server virtual directory (UI pages, scripts and images) must be placed in the applications www directory, named <app_id> -www.

CGI scripts that should be executed by the web server to dynamically generate UI pages must be placed inside the applications cgi-bin directory, named cgi-bin and located inside the application's www directory.

Page 20 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

8.1.1 Application Localization

The LifeLine SDK handles the localization of your application entry point (icon) in the LifeLine UI, including its name, description, and keywords fields. This is done by the SDK branding mechanism, which supports _gettext _ attributes, in the fields of the application.xml. The languages currently supported by LifeLine are: German / Deutsch (de) English (en) English-US (en_US) Spanish / Espaol (es) French / Franais (fr) Italian / Italiano (it) Dutch / Nederlands (nl) Polish / Polski (pl) Brazilian Portuguese / Portugus Brasileiro (pt_BR) Swedish / Svenska (sv) Turkish / Trke (tr) Russian / (ru) Hebrew / ( he) Arabic / ( ar) Japanese / (ja) Chinese Simplified / (zh_CN) Chinese Traditional / (zh_TW) Korean / (ko) The LifeLine web server localizes the strings returned to the client based on the value of the AcceptLanguage field in the header of the HTTP request sent by the client. This value is usually set by the browser to match the language of the users environment. However, if your SDK application requires a specific language, the UI pages of the application can override the value of the Accept-Language header field before the HTTP requests are sent to the server. A simple way to set the language is to use the jQuery function $.ajaxSetup, which allows the UI page to configure the header field values that should be used for all subsequent requests issued by that page.

8.1.2 LifeLine Parser

The LifeLine parser provides a range of auxiliary functions for the HTML files that reside in the applications www directory. Once "wwwDir" and lifeLineParser are enabled in an application.xml file, its pages can use: localization, using the LifeLine native translation database, along with any localized strings defined in the application's application.XML file. Translations are based on the first supported language that can be found in the "Accept-Language" property of the incoming request header. encoding for XML, JavaScript or any combination of them. boolean logic device and page properties

Page 21 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

The localization routines from the LifeLine Parser present the same behavior of the gettext library, including the translation of an empty string into the translation header information. Because of this, SDK applications must take the necessary measures to ensure that their UI pages never request the translation of an empty string. Doing so would result in a large amount of text being returned and displayed in the place of the expected translated strings. A complete description for all available functions is in the "LifeLine Parser Guide". These functions are executed on the server side, before the Apache server returns the requested html page to the client. To invoke any of these functions, they must be included anywhere in the html or JavaScript code of the pages, preceded by the "@@" tag. For example: @@_x("Text to translate"): Translate the quoted text, using LifeLine's native database of localized strings, as well as any localized strings defined in the application.xml file. @@_api("Feature", 52): Get the JSON response from the "Feature" REST API, for the feature with id 52.

8.1.3 Session Flags

Along with the functions listed in the LifeLine Parser Guide, there is one additional function that can be used in an application's HTML pages: checkflags(). This function allows the page to enforce which restrictions apply to it. You must add these checks to the beginning of your applications HTML pages, so they can be evaluated before returning the pages to the client. If any check fails, a redirect page is returned instead. In the following examples, the first statement is the checkflags function, and the second statement is the redirection. <% checkflags(adminreq) %>: The current user must be logged in as an admin to see this page. Otherwise, the user is redirected to the LifeLine login page. <% checkflags(securityreq) %>: Security must be enabled in the device for this page to be loaded. Otherwise, the user in redirected to the LifeLine home page. <% checkflags(allowie6) %>: This flag allows the page to be served to IE6. When disabled, IE6 users are redirected to an error page. The complete list of restriction flags is available in the "Session Flags" enumeration value in the LifeLine API documentation.

9 Building Your Application

Modify the makefile to include the files in your application directory and then compile your code for one of the supported architectures.

10 Creating an Application Set

You start creating your application set in any directory on your build machine where you installed the SDK. 1. Enter the following commands in a shell prompt to begin creating your application set: o2 create-set <application set id> <vendor name> For example, o2 create-set sampleAppSet companyXYZ This command creates an application set directory that has the same name as the application set that you specified, for example, sampleAppSet. 2. Change to the application set directory created by the previous step.

Page 22 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd. For example, cd sampleAppSet

CONFIDENTIAL AND PROPRIETARY

You will find the following files in the application set directory: <app set id>.xml: This file defines constant values about the application set, its vendor, and the applications contained in the set. The application set can contain one or more applications. The file is used to create the final tgz file that can be installed on the LifeLine devices. <app set id>_upgrade.xml: This file defines additional parameters for the installation and upgrade of the application set and its applications. The file is always included in the TGZ file, to be used to upgrade previously installed versions of the application set on the LifeLine devices or install it from scratch. For more information, refer to Upgrade Info XML File. Makefile: The utility that builds your SDK application set.

10.1 Modifying the <application set id>.xml File

Use the application set configuration file (<application set name>.xml) to define constant values about the application set from a specific vendor. The file is written in XML UTF-8 format and looks like the following: <?xml version="1.0" encoding="utf-8" ?> <vendor name="companyXYZ"> <description>Company XYZ develops SDK applications</description> <copyright>Company XYZ</copyright> <applicationSet id="sampleAppSet" displayName="Sample SDK Applications" version="1.0"> <description>This is a sample set</description> <upgradeInfo>http://www.companyxyz.com/sampleAppSet_upgradeInfo.xml</upgradeInfo> <application id="sampleAppId" delete="0"/> <application id="sampleAppId2" delete="1"/> </applicationSet> </vendor> Every application set contains a version, a description of the application set, and one or more applications.

10.2 Application Set Parameters

When you create your application set, you modify parameters that are in the applicationSet.xml file. The following table lists the modifiable parameters and their definitions.

<vendor/name>

Application Set vendor name. This should be the same name as the one in the Application configuration file. Description for the vendor. This is not displayed in the LifeLine UI. The company that holds the application set copyright. A unique identifier for an application set that supports alpha characters only. This is not displayed to the user.

<vendor>/<description> <copyright> <applicationSet/id>

Page 23 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

This was formerly the "name" attribute. The name attribute is retained for backward compatibility but will be phased out in two releases. <applicationSet/displayName> Application Set name. This is displayed in the LifeLine UI on the list of installed application sets in the Application Manager page. This display name can be localized. Application Set version. This is displayed in the LifeLine UI in the list of installed application sets on the Application Manager page. Flag used to prevent the application set from being uninstalled. If this flag is set, once the application set is installed, it cannot be uninstalled using the LifeLine APIs. Application Set description. This is not displayed in the LifeLine UI. URL of the remote XML file that contains information about the latest update that is available for the application set. ID of one of the applications in the application set. This field should not be edited manually. Flag used to delete an application during the application set upgrade process. For more information, refer to section 16.

<applicationSet/version>

<applicationSet/blockuninstall>

<applicationSet>/<description> <upgradeInfo>

<application/id> <application/delete>

10.3 Building Your Application Set

Start by including the applications in your application set. 1. In the parent directory of the application set, enter the following command in a shell prompt to include applications to your application set: o2 manage-set <application set id> addapp <application id> For example, o2 manage-set appsettest addapp cgitest 2. Change to the application set directory and generate the installation package for the desired architecture. If any of the applications in the set has not been compiled yet, it will be automatically compiled for the indicated target now: make target=<architecture> For example, make target=i686-vmware

11 Testing Your Applications

Install your application set on a target device, such as a virtual machine or other LenovoEMC NAS device, using that target devices Application Manager UI feature or with REST commands to the AppManager. Refer to Upgrade through the REST APIs for information on installing an application set through REST APIs.

Page 24 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

11.1 Setting up the LifeLine VM

As part of your application testing, you should set up the LifeLine virtual machine that is included with the LifeLine SDK. 1. Refer to the Getting Started section for information on downloading the LifeLine SDK, which includes the VMware image. The VMware image is located at: $LLSDK_HOME\vm You must unzip the sohovm-<release number>.zip file in this directory to get the actual vm image file (*.vmx). For example, look for the file called sohovm-3.2.1.42000.zip. 2. Unzip this file into the directory where it currently exists. The final VM image file (*.vmx) is located at: $LLSDK_HOME\vm\soho 3. To start up this VM, you must first set up the VM image in either VMware Workstation or VMware Player. 4. In VMware, click File, Open. Browse to the soho directory where you unzipped the VM image file and click Open. 5. After VMware loads the VM, you can start it by powering it on. When VMware prompts you if you moved or copied the image, select copy. 6. After the VM powers up, log in to the VM console with these credentials: login: root password: soho You can execute standard Unix commands from the VM console. 7. Change the network adapter network connection to Bridged. To do this, click VM, Settings. Select Network Adapter under the Hardware tab. Select Bridged under the Network connection section. 8. To connect to the VM through a web browser, obtain the IP address of the network interface on the VM. Log in to the VM as root, type the command ifconfig, and get the IP address of interface eth0. 9. Enter the IP address you obtained in a web browser. For example, the IP address might be 192.168.1.9. This opens the Setup page of the VM.

11.2 Login Credentials with Security Enabled

If you enable security on the VM, you are required to create an administrator user and password to access the user interface. The administrator password is appended to the initial password. For example, if you create a LifeLine administrator user called admin and assign a password of admin, the login credentials are for the VM: login: root password: sohoadmin The login credentials are also used for SSH.

12 Designing More Advanced Applications

The following sections describe optional features that a developer can include with an application.

Page 25 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

12.1 Interprocess Communication Between LifeLine and SDK Applications

There are currently two ways for LifeLine and SDK applications to communicate with each other: LifeLine communicates with applications through the Interprocess Communication mechanism (IPC). Refer to Library for the Inter Process Communication (IPC) Mechanism for more information. Applications communicate with LifeLine through REST APIs.

12.1.1 Third-party Application functions

When the LifeLine application manager starts an installed third-party application, it can call the optional Setup and Authentication functions for the applications. These functions run if they are specified by parameters in the applications application.xml file. Refer to Application Parameters for more information. 12.1.1.1 Setup function This defines any function(s) that is called during the setup sequence. gboolean setUpApp(CPResult_t result, char** message) 12.1.1.2 Authentication Function This function is called for authentication purposes. gboolean authenticateFunction(CPResult_t result, char** message) message Displays any error messages in the UI.

12.1.2 Library for the Inter Process Communication (IPC) Mechanism

To use the IPC mechanism, an SDK application must use the CPipc library, as follows: The application should be linked to the CPipc library by adding the following lines to the application's Makefile: APP_LDFLAGS += -lCPipc-2.2 -lsoup-2.4 CFLAGS += -I$(ARCH_DIR)/usr/include/CP-2.2 CFLAGS += -I$(ARCH_DIR)/usr/include/libsoup-2.4 A new version of this library is always created for each new LifeLine SDK version and the name of the librarys binary file contains its current version number. This version number always matches the version number of the LifeLine REST APIs. Because of this, the lines above must always be updated when an SDK application is migrated to a new version of the LifeLine SDK. The application source file that calls the CPipc library functions must add the following #include directive: #include <CP/CPipc.h> All the functions in the CPipc header file must be used only by the executable defined in the executable tag of the application.xml file. The CPipc library exposes the following functions: CPStatus_t cpIpcInit(); CPStatus_t cpIpcRegisterCallback(const char *methodName, CPIpcCallback_t callback); CPStatus_t cpIpcStartListener(const char *name); CPStatus_t cpIpcStopListener();

Page 26 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd. CPStatus_t cpIpcCleanup(); void cpIpcSetThreadUser(const char *user); void cpIpcSetThreadLanguage(const char *lang);

CONFIDENTIAL AND PROPRIETARY

CPIpcCallback_t is defined as follows: typedef void (*CPIpcCallback_t) (const char *contextin, const char *xmlin, char **xmlout, CPResult_t *result); This means the callback functions receive two strings (contextin and xmlin) and return one string (xmlout) and a result. The contextin parameter is an XML string containing context information about the IPC call. This XML is in the following format: <context><session>session_id</session><language>language</language></context> When the incoming XML-RPC data is originated by a REST API call, the session_id string contains the id of the current Apache session associated with the REST API call. This session id can be used in the form of a cookie to issue additional REST API calls to LifeLine without the need to perform a login. The session_id string may be empty if there is no Apache session associated with the IPC call. The language string is an identifier of the language associated with the IPC call that may be used for internationalization purposes. The xmlin parameter follows the XML-RPC specification, as specified by http://www.xmlrpc.com. The xmlout output value must also be in XML-RPC format. The result output value must contain a status code. If the status code is not ME_OK, a description must also be returned. The possible values for the status code can be found in the CP/Result.h file. After registering a function and starting the listener, any IPC call can trigger the specified callback function. 12.1.2.1 Exposed Functions CPStatus_t cpIpcInit(); This function initializes the CPipc library and must be called once before calling any of the other library functions. CPStatus_t cpIpcCleanup(); This function performs a cleanup on the CPipc library, removing all registered callbacks. It is the counterpart to cpIpcInit() and should be called once after the application is done using the CPipc library. Applications are responsible for removing all their registered callbacks before being uninstalled from the device. This can be achieved by using a callback for the SoftwareUninstall API, according to the details in section 12.7. CPStatus_t cpIpcRegisterCallback(const char *methodName, CPIpcCallback_t callback); This function registers an entry point into the SDK application that may be called by LifeLine or by other SDK applications, and it must always be called by the same executable as specified in the executable tag of the application.xml file. The first parameter, methodName, specifies the name of the API that is exposed to external processes. The second parameter, callback, is a pointer to a callback inside the SDK application. CPStatus_t cpIpcStartListener(const char *name);

Page 27 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

This function starts a new thread that listens for IPC calls. When this thread receives a call to any of the registered entry points, it calls the associated callback function. The name parameter is used to uniquely identify the SDK application to the IPC mechanism. Therefore, it must be composed of both the vendor name and the application id, in the form: <vendor>_<app_id>. For example, companyXYZ_sampleAppIdentity. CPStatus_t cpIpcStopListener(); This function stops the IPC listener thread. All the CPipc library functions return a CPStatus_t result. On success, ME_OK is returned. Any other value means an error occurred. void cpIpcSetThreadUser(const char *user); This function associates the current thread with any existing LifeLine user, regardless if it is an administrator user or not. After this is done, the current thread inherits all access permissions that have been configured for that user in LifeLine, with respect to subsequent calls to LifeLine APIs done via the CPipc library. This feature is particularly useful when calling LifeLine APIs that require administrator credentials. In this case, the current thread must be associated with an existing LifeLine administrator user. void cpIpcSetThreadLanguage(const char *lang); Similar to the previous function, this function changes the language associated with the current thread. This causes LifeLine to return localized texts and error messages when calling LifeLine APIs via the CPipc library. In addition, additional regional settings are also applied to the values returned by LifeLine, such as right-to-left text, number format, date format, etc. The language values supported by this feature are listed in section 8.1.1Error! Reference source not found.. 12.1.2.1.1 IPC Samples There are two samples using IPC: ipctest and ipccallback. These are contained in the sdksamples application set. To run these applications: 1. Install the application set 2. Run the desired sample: /opt/apps/vendor/sample 3. Call the desired method using the /usr/local/cp-utils/cp-sdkipc utility 12.1.2.1.2 ipctest ipctest is a simple application containing two functions, printTime and quit. These functions are registered. The function printTime writes the devices current date/time to the console, if ipctest was executed manually. The function quit stops the application. A user can test these functions through the test utility program cp-sdkipc, using the following commands: /usr/local/cp-utils/cp-sdkipc call ipctest lenovoemc "<methodCall><methodName>printTime</methodName><params/></methodCall>" /usr/local/cp-utils/cp-sdkipc call ipctest lenovoemc "<methodCall><methodName>quit</methodName><params/></methodCall>" Where the first command outputs the date and time, and the other command quits the application.

12.1.2.1.2.1

Troubleshooting

Page 28 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

Problem: I cannot see the current time when I call the printTime callback. Solution: To see the output, ipctest must be run interactively from a console. This is necessary because the current time is displayed on the terminal where ipctest is running and not on the terminal where cpsdkipc was invoked. One way to accomplish that is to first stop the running ipctest and then start it again manually, as illustrated by the following commands: /usr/local/cp-utils/cp-appmd stop ipctest cd /opt/apps/lenovoemc/ipctest ./ipctest Now, on a different terminal, invoke the printTime callback with cp-sdkipc and go back to the terminal where ipctest is running to see the output. Problem: Unable to retrieve information. /usr/local/cp-utils/cp-sdkipc call ipctest lenovoemc "<methodCall><methodName>printTime</methodName><params/></methodCall>" Error: Unable to retrieve the requested information. Solution: Be sure your application is running before calling the method. If your application is running, check for the APPID value in the main.c file. If your application was copied from another file, this #define must be updated as well. 12.1.2.1.3 ipccallback This application shows how to create functions that are triggered from LifeLine when special events occur. This is made by registering three callback functions: sampleSetupFunc sampleAuthenticateFunc

Each one has its corresponding function defined in the application configuration file. Note that the value set in this xml attribute must be an exact match of the function name used as a callback. 12.1.2.2 Common Build Errors Be sure to have CPipc in your Makefile APP_LDFLAGS += -lCPipc-2 -lsoup-2.4 CFLAGS += -I$(ARCH_DIR)/usr/include/libsoup-2.4 CFLAGS += -I$(ARCH_DIR)/usr/include/CP-2 The o2 create script does not enable the CPipc library by default in the makefile it creates, but it includes the above line commented out. You must uncomment it to enable the CPipc library.

12.2 Events
There are currently two ways for SDK applications to interact with LifeLine events: Applications can register for events coming from LifeLine using the CallbackEventRegister REST API. The application must expose a REST API that is called when the registered event is broadcasted by LifeLine, e.g.:

http://<device_ip>/cp/CallbackEventRegister?v=2&id=sharedelete&function=companyXYZ_SampleAppEv entHandler

Page 29 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

To stop being notified about specific events, the SDK application must make a similar call to the CallbackEventDeregister API, e.g.: http://<device_ip>/cp/CallbackEventDeregister?v=2&id=sharedelete&function=companyXYZ_SampleApp EventHandler For details about exposing new APIs, refer to section 12.6. Applications are responsible for removing all their registered callbacks before being uninstalled from the device. This can be achieved with the use of a callback for the SoftwareUninstall API, according to the details in section 12.7 Applications can generate events that go into LifeLine using the "EventSend" REST API. These events are propagated internally to all LifeLine native applications and also broadcasted over DBus as signals and automatically forwarded to registered event handlers.

Note: If your application interacts with LifeLine events, you should be aware that events are subject to change from one release of LifeLine to another and this may prevent your application from interacting with events in future releases. There is no guarantee of backward compatibility.

12.2.1.1 Event Samples There is one sample using LifeLine events: deferredevent. This is contained in the sdksamples application set. To run this application: 1. Install the application set 2. Access the UI page of the application: Deferred Event Sample on the All Features page. DeferredEvent is a simple application that monitors LifeLine events broadcasted through its registered APIs. Output from this process is written to the system log on /var/log/messages. A user can test the monitoring of LifeLine events by changing which events are monitored by the application using its UI page and forcing the device to broadcast these events to see what is written to the system log.

12.3 Redirection APIs

Use the redirection APIs to redirect any LifeLine html page to another one of your choice. For example, you might want to implement your own video surveillance page. For example, to implement your own video surveillance page, use the Redirection APIs to link to your page when a user clicks the video surveillance link in LifeLine. LifeLine APIs provide two different kinds of redirection mechanisms: selective redirection and global redirection. The two redirection mechanisms are explained below. RedirectPageAdd(path, page, password); This API redirects the specified html page argument (specified without the .html extension) to the html file specified by the path argument. Note that LifeLine UI html pages can be redirected to the SDK Application pages, but you cannot redirect to LifeLine UI pages from the SDK pages. All configured page redirections are permanent until explicitly deleted. RedirectPageDelete(page, password) This API deletes a previously added html page redirection. The password parameter is optional. It is possible to add and delete redirections without using a password. However, if a password is set, you cannot add or delete redirections without entering the password.

Page 30 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

12.3.1 Selective Redirection

To permanently set a page redirection to a specific page, you call the RedirectPageAdd API and pass the page to be redirected as an argument. For instance, the REST call: http://<device_ip>/cp/RedirectPageAdd?v=1.1&path=/apps/vendor/testapp/mylogpage.html& password=pass&page=log redirects the log.html page to the mylogpage.html page contained in the www directory of the testapp application. This type of redirection can be stopped by RedirectPageDelete APIs. See the example below.

12.3.2 Global Redirection

A global redirection (any page being redirected to the same html page) is made by leaving the page empty: http://<device_ip>/cp/RedirectPageAdd?v=1.1&path=/apps/vendor/testapp/mypage.html& password=pass&page= In this example, all pages under http://<device_ip>/ are redirected to mypage.html, which is contained in the www directory of the testapp application. This type of redirection can be stopped by RedirectPageDelete APIs. See the example below. 12.3.2.1 Device initialization The LifeLine UI initializes the device the first time a user or application accesses a UI page using the "SystemModify" API: http://<device_ip>/cp/systemmodify?v=1&system:initialized=1 If an SDK application that uses global redirection is automatically installed during the initial setup of the device (see Appendix C Installing Partners Applications at Manufacturing), a user never sees the original LifeLine UI. As a result, the device is not automatically marked as "initialized". If the device is not initialized, scheduled tasks, such as the automatic firmware upgrade, are not executed. Any SDK application you create that uses global redirection must make a call to the SystemModify API during its own initialization, so that the device is also initialized.

12.3.3 Stopping Redirection

To permanently remove a previously configured redirection, call RedirectPageDelete when the redirection is no longer suitable or desired. For example, to stop redirecting the log.html page in the first example: http://<device_ip>/cp/RedirectPageDelete?v=1.1&password=pass&page=log And, to stop the global redirection: http://<device_ip>/cp/RedirectPageDelete?v=1.1&password=pass&page=

12.3.4 Homepage Redirection

This is a special case of selective redirection. You can redirect the home page of the LifeLine web UI by adding a redirection with index as the page parameter: http://<device_ip>/cp/RedirectPageAdd?v=1.1&path=/apps/vendor/testapp/mypage.html& password=pass&page=index To cancel homepage redirection, use the RedirectPageDelete API with the same parameter: http://<device_ip>/cp/RedirectPageDelete?v=1.1&password=pass&page=index

Page 31 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

12.3.5 Redirection sample

The redirection sample included in the sdksamples application set contains a simple example of page redirection. By running it once, the home page is redirected to an index page under the www directory of the redirection application. This page contains links which call the RedirectPage APIs to add or delete redirection pages.

12.4 Custom home page

Instead of redirecting the home page of the LifeLine web UI, an SDK application can simply change its appearance or behavior, using the HomeInfoModify API. This has the advantage of not requiring the creation of a new page from scratch. However, the HomeInfoModify API can also be used to redirect the home page to a custom page, created from scratch and hosted in one of the user shares or in the applications directory. This is particularly useful when you want to allow users to easily disable the home page redirection and get back to the original LifeLine home page. When compared with the Redirection APIs, this method of redirection has the disadvantage of not being protected by a password. Refer to the REST API documentation for additional details about the API and refer to the Custom Home Page sdk sample for examples of how to use this feature.

12.5 Linux Kernel Module Development

The LifeLine SDK contains the Linux Kernel sources required to develop loadable kernel modules. To enable kernel module support, follow this procedure: 1. Create an application, apptest. Refer to Creating a LifeLine Application for more information. 2. Enable ko-support with the command: o2 enable-ko-support <application name> $ o2 enable-ko-support apptest 3. Place the kernel modules under <application directory>/ko $ cp mykernelmodule apptest/ko 4. Add the kernel modules to the makefile that was created under the <application directory>/ko directory, in the obj-m entry: obj-m += mykernelmodule.o The helloko sample contains an example of an application containing a kernel module.

12.6 Exposing New REST APIs

The LifeLine SDK allows applications to expose their own REST APIs. These REST APIs are defined in the sdkapi.xml file and called by client pages through HTTP, using the following syntax: http://<device_ip>/cp/<vendor>_<function_id>?v=1&<parameter>=<value>&...&<parameter>=<va lue>

12.6.1 sdkapi.xml definition

The new APIs should be declared in the "sdkapi.xml" file. This file is written in XML UTF-8 format and looks like the following:

Page 32 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

<?xml version="1.0" encoding="utf-8"?> <APIDoc> <Subsection vendor="companyXYZ" app="sampleAppIdentity"> <Struct Tag="api_three_info"> <Title>SDK API Three input structure</Title> <Param Tag="text" Type="string"/> <Param Tag="number" Type="i4"/> </Struct> <Struct Tag="api_four_info"> <Title>SDK API Four output structure</Title> <Param Tag="text" Type="string"/> <Param Tag="number" Type="i4"/> </Struct> <Function Id="SDKApiOne"> <Description>Test SDK API one</Description> <Args> <Param Tag="text" Type="string" Optional="1"/> <Param Tag="number" Type="i4" Optional="1"/> </Args> </Function> <Function Id="SDKApiTwo"> <Description>Test SDK API two</Description> <Return Type="string"/> </Function> <Function Id="SDKApiThree"> <Description>Test SDK API three</Description> <Args> <Param Tag="input" Type="struct"> <Struct Reference="api_three_info"/> </Param> </Args> </Function> <Function Id="SDKApiFour"> <Description>Test SDK API four</Description> <Return Type="struct"> <Struct Reference="api_four_info"/>

Page 33 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd. </Return> </Function> </Subsection> </APIDoc>

CONFIDENTIAL AND PROPRIETARY

12.6.2 SDK API parameters

When you create your application, you define the contents of the sdkapi.xml file according to your needs. The following table lists the supported elements and their definitions.

SDK API Parameter <Subsection/vendor> <Subsection/app> <Struct> <Struct/Tag> <Struct/Title> <Struct/Reference> <Param> <Param/Tag> <Param/Type>

Definition Vendor name of the application that exposes these APIs. Unique identifier of the application that exposes these APIs. Used to define structures to be referenced by the API definitions, following the XML-RPC format. The unique identifier of the structure. A textual description of the structure, used only for documentation. Used to make reference to a previously defined structure. May be added as the contents of any "Param" or "Return" tag. Used to define a newly named parameter that may be part of a structure or an API definition. The name of the parameter. The XML-RPC type of the parameter. This must be one of: i4, i8, string, boolean, struct, array, base64 and dateTime.iso8601. If the "struct" type is used, a reference to a previously defined "Struct" must be included as a child element. Used to define a new REST API. The unique identifier of the API A textual description of the API, used only for documentation. The array of arguments for the API. This may include any number of "Param" or "Struct" tags. The XML-RPC type of the return. This must be one of: i4, i8, string, boolean, struct, array, base64 and dateTime.iso8601. If the "struct" type is used, a reference to a previously defined "Struct" must be included as a child element.

<Function> <Function/Id> <Function/Description> <Function/Args> <Function/Return/Type>

Page 34 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

12.6.3 Registering DBus Callbacks

To handle the REST API calls, your application must register one callback for each "Function" defined in the sdkapi.xml file. These callbacks may be registered using the CPipc library, according to the details in section 12.1.2. The CPipc library must only be used by the executable defined in the executable tag of the application.xml file. The "methodName" passed on to the registration function must be composed of the vendor name and the "Id" attribute of the "Function" defined in the sdkapi.xml file, in the <vendor>_<id> format, e.g.: cpIpcRegisterCallback (companyXYZ_SDKApiOne, sdkApiOneCallback) Refer to the "sdkapitest" sample SDK application for examples of how to handle and parse the incoming XML-RPC request.

12.6.4 Incoming data

These REST calls are parsed by LifeLine and forwarded to the application process through DBUS IPC, using the standard format of the XML-RPC specification. The parameters added to the REST call are included in the XML-RPC request that is forwarded to the application in the form of name-value pairs, inside of a hash table. The hash table is the only param element present in the incoming XML data, e.g.: <methodCall> <methodName>companyXYZ_ SDKApiOne</methodName> <params> <param> <value> <struct> <member> <name>text</name> <value><string>sample text</string></value> </member> <member> <name>number</name> <value><int>5</int></value> </member> <member> <name>v</name> <value><double>2</double></value> </member> </struct> </value> </param> </params> </methodCall>

Page 35 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

12.7 Registering callbacks for LifeLine REST APIs

The LifeLine SDK allows SDK applications to register callback functions to selected LifeLine REST APIs. These callback functions are invoked when their respective LifeLine APIs are called to do any desired pre-processing required for the API call. The LifeLine REST APIs that support callbacks are identified in the Callback Definitions section of the LifeLine REST API documentation, with a suffix indicating the type of callback functions supported by that API, e.g.: ShareDeleteCheck, ShareDeleteComplete: The ShareDelete API only supports Check and Complete callback functions. The exact order in which the callback functions are invoked depends on the type of the callback: XXXXCheck: This function gives an opportunity to abort the API operation and return a message to the user. It should not alter the state of the system, since being called doesn't necessarily indicate that the API operation will occur. This function may return the ME_CONFIRM result code to require the user to confirm the API operation. This may be used alone or as part of a Check, Prepare, Done sequence. This allows, for example, an SDK application to prevent a user share from being deleted in case it contains important user data. At this point, the original API caller has the option to repeat the same API call, setting the force parameter to true. This causes all the Check callback functions that are registered with that API to be skipped. XXXXPrepare: This function allows an SDK application to prepare for an operation prior to it happening and cannot abort the operation. The Prepare functions are only invoked if none of the Check functions returned ME_CONFIRM or if the force flag was specified in the API call. This function should not permanently complete the operation, as it may be necessary to revert these changes in the Done function. This callback is always defined with ReturnVoid="1". After all Prepare functions are invoked, the actual API operation is performed. XXXXVerify: This function is called after an API operation completes, to give the opportunity for an SDK application to request that the API operation be reverted prior to reporting completion. This function can be used in conjunction with XXXXDone or on its own. If a Verify function returns any status code other than ME_OK, the operation is aborted and the provided text message is displayed to the user. As with the XXXXCheck function, this function should not modify state. If actions must be taken to revert or complete an operation, the XXXXDone function must be used for that. XXXXDone: This function is called after the API operation is finished. This function always includes a "failed" boolean input parameter, which indicates whether the API operation actually succeeded. A XXXXDone function should only be used in conjunction with the XXXXPrepare function, and it provides a way for SDK applications to rollback changes done in the XXXXPrepare function on failure, or to finalize changes placed in an intermediate state on success. This function is always defined with ReturnVoid="1". XXXXComplete: This function is very similar to an event, except that the operation is synchronous. It is called after the API operation completes successfully (and all XXXXDone callback functions have been invoked) and is always defined with ReturnVoid="1".

To register a callback for one of the APIs that support that, the SDK application must add an entry to the sdkCallback.xml file: <Callback Name="SampleAppShareDeleteCheck" Reference="ShareDeleteCheck" /> There is no need to declare a body for the callback function in the XML file, since it is mandatory for the callback function to receive exactly the same parameters as the referenced CallbackDefinition. In addition to the XML definition, the SDK applications executable must register a backend function to handle this callback using the CPipc library, according to the details in section 12.1.2: cpIpcRegisterCallback("lenovoemc_SampleAppShareDeleteCheck", sharedeletecheckcallback);

Page 36 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

Finally, to interrupt the execution of the original LifeLine API for any reason, the backend function of a Check callback should simply return the ME_CONFIRM status code, accompanied by a suitable description of the reason why the API cant be processed at that moment. Applications should also use a callback for the SoftwareUninstall API to remove all their registered LifeLine API callbacks, using the cpIpcCleanup function of the CPipc library.

12.8 Deferred Schedule

The deferred schedule feature of LifeLine allows an SDK application to register an API function for a particular scheduled time. Once the specified scheduled time is reached, this API is called.

12.8.1 Registering a Schedule

Applications can schedule a job to be run in the future and then exit. When the schedule is supposed to run, the application restarts automatically and the corresponding API is called. SDK applications can register a scheduled job using the CallbackScheduleRegister API, which takes the following parameters: name: A name for the scheduled job which should be unique within an application function: The name of the API of the application that should be called (See 12.6) data: The data that the user can set and send to the API being called schedule: The schedule structure that has the following fields: enabled: If set to true, the schedule is currently enabled. If set to false, all other parameters are disabled. start: The time a task starts, represented as a number of minutes after midnight stop: The time a task stops, represented as a number of minutes after midnight days: The days of the week the scheduled job runs repeat: The frequency at which the scheduled job runs, for example, every hour, two hours, and so on flags: Indicates if the scheduled job should run only once and if this particular scheduled job should persist or not. Non persisted schedules do not run after a reboot. For more information on these parameters, refer to the SDK API Documentation. If the storage device powers off before the next scheduled job runs, the next time the storage device powers up, this scheduled job runs immediately. For example, if a scheduled job is set to run at 12 a.m. and the storage device is powered off before that time, the next time the device powers back up, the scheduled job immediately, regardless of the time. If the SDK application is uninstalled, all the corresponding schedules are removed automatically.

12.8.2 Deregistering a Schedule

For deregistration of a scheduled job, the SDK application should call the CallbackScheduleDeregister API, providing the schedule name and the API name. If only an API name is specified, all the schedules for that API will be removed. Applications are responsible for removing all their registered scheduled jobs before being uninstalled from the device. This can be achieved with the use of a callback for the SoftwareUninstall API, according to the details in section 12.7.

Page 37 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

12.9 Custom apache module

The LifeLine SDK allows SDK applications to specify a custom apache module of their own that are used to handle HTTP requests directed at the applications URLs. This custom apache module may be used to produce any non-standard behavior that is required by the application. Each application in an application set can use its own custom module, but no more than one custom module can be used by each application. Each application can also determine which one of its directories should use the custom module: the www directory, the cgibin directory, or both. To use this feature, the source code of the custom apache module must be included in the source code directory of the application, to be cross-compiled for all required targets together with the SDK application. The following changes should be made in the Makefile of the SDK application: Uncomment the definition of the apache flags:

APACHE_CFLAGS = -DLINUX=2 \ -D_GNU_SOURCE \ -D_LARGEFILE64_SOURCE \ -D_REENTRANT \ -I$(LLSDK_HOME)/$(arch)/usr/local/apache/include \ -L$(LLSDK_HOME)/$(arch)/usr/local/apache/lib Uncomment the GCC compilation command:

mkdir -p modules/$(target) $(CC) <module .c source file> -fPIC -shared -o modules/$(target)/<output .so library> $(APACHE_CFLAGS) $(CFLAGS) cp -rf modules/$(target)/<output .so library> $(PKG_DIR) The following values should be configured in the application.xml file: application/custommodule: This flag enables the custom apache module feature. webserver/custommodule/path: The path to the .so file. The path must be relative to the applications base directory. This is the path used in the LoadModule directive in the apache configuration file. webserver/custommodule/module: This is the name of the external variable of type module defined in the source code of the custom module, which is also listed as the Module Identifier in the module documentation. This is the name of the symbol used in the LoadModule directive. webserver/custommodule/handler: The name of the actual handler declared in the .so file. This is the value used in the Directory/SetHandler directive in the apache configuration file. webserver/custommodule/www: This flag specifies whether the custom module should handle requests directed at the URLs of the applications www directory. This includes all subdirectories of the www directory, except for the cgi-bin directory, which has its own setting, e.g.: http://<device_ip>/apps/companyXYZ/sampleapp/[...] http://<device_ip>/apps/companyXYZ/sampleapp/images/[...] webserver/custommodule/cgibin: This flag specifies whether the custom module should handle requests directed at the URLs of the applications cgi-bin directory. This includes all subdirectories of the www directory, e.g.: http://<device_ip>/apps/companyXYZ/sampleapp/cgi-bin/[...] http://<device_ip>/apps/companyXYZ/sampleapp/cgi-bin/setup/[...] The remaining parameters used in all Directory entries for the application are fixed: Options -Indexes FollowSymlinks MultiViews

Page 38 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd. AllowOverride None Order allow, deny Allow from all

CONFIDENTIAL AND PROPRIETARY

Refer to the Custom Apache Module sample SDK application for an example of how to compile and configure the custom apache module.

12.10

Calling LifeLine API from the backend

The LifeLine SDK allows executable files that run on the backend to use the CPipc library to issue direct calls to LifeLine APIs, just like regular functions, instead of an HTTP library to issue the calls via HTTP. This mechanism makes it much easier for the backend executables to interact with LifeLine, as well as having the advantage of not requiring the caller to parse the JSON responses received through HTTP. To use this feature, the Makefile of the application must link to the CPipc library, as described in section 12.1.2, and the executable file must include the CP/CPapi.h header file: #include <CP/CPapi.h> The header file above includes all the header files required to be able to use this feature. The actual function signatures for all LifeLine APIs are defined in the CP/cpFuncs.h header file. They are usually in the format: CPStatus_t cp<API name>(CPResult_t *res, [input parameters], <type> **ret) Where: CPStatus_t: the result of the API call, indicating success (ME_OK) or failure (any other value) res: a pointer to an allocated structure that holds the detailed result of the API call. If any value other than ME_OK is returned by the function call, the description field of this struct contain s a textual description of the error. [input parameters]: the input parameters required by the API, in the same order as described in the API documentation. ret: the address of a pointer of the type specified in the API documentation. This pointer is modified to reference the return value of the API, which is dynamically allocated by the API function.

These dynamically allocated values must be freed from memory by the caller when they are no longer used. The CP/structfns.h header file exposes some utility functions to free complex structure returned by the LifeLine APIs The CP/ListUtil.h header file exposes some utility functions to work with lists returned by the LifeLine APIs. The CP/cpStructs.h header file exposes functions to free each of the struct types defined by the LifeLine APIs. In case the LifeLine API being called requires the caller to have administrator credentials, you must use the cpIpcSetThreadUser function to associate the current thread with an existing LifeLine administrator user account. Refer to section 12.1.2.1 for details.

12.11

Web server proxy configuration

The LifeLine SDK allows SDK applications to start a custom web server to handle specific incoming requests. To selectively redirect incoming request to their own web servers, SDK applications can create their own proxy configuration in the default web server used by LifeLine.

Page 39 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

SDK applications choose a custom path under their base URL to be redirected to their custom web server, which must be running on different ports than the default LifeLine web server (80 for HTTP and 443 for HTTPS). No more than one proxy configuration can be created by each SDK application. Each application can determine which type of traffic gets redirected to their custom web server: HTTP, HTTPS, or both; and also which port to use for each type. To use this feature, the SDK application must start its custom web server when necessary, and the following values should be configured in the application.xml file: application/proxy: This flag enables the proxy feature. webserver/proxy/location: The path under the base URL of the SDK application that is redirected to the custom web server. This path must match the exact path that is going to be redirected to the custom web server, including the leading /. For example: /sampleProxy redirects all requests directed at: http://<device_ip>/apps/companyXYZ/sampleapp/sampleProxy/[...] webserver/proxy/http: This is the port on which the custom web server listens for regular HTTP traffic. webserver/proxy/https: This is the port on which the custom web server listens for regular HTTPS traffic.

Refer to the Proxy sample SDK application for an example of how to configure the web server proxy.

12.12

Email notifications

The EmailSend LifeLine API allows SDK applications to easily send notification emails to the email addresses provided by the device administrator on the Email Notification page of the LifeLine Web UI. In case the administrator has not provided a custom SMTP setting, LifeLine uses the default SMTP server, which has a daily limit of 50 emails for each sender IP. SDK applications can override the SMTP settings using the EmailModify LifeLine API to use a custom SMTP server without this limitation. Refer to the REST API documentation for additional details about the APIs.

12.13

Video output support

The px LifeLine devices allow the user to connect a PC monitor directly to the VGA/HDMI port and a keyboard to any of the USB ports on the back of the device, to operate it without the need of a PC or an Ethernet network. LifeLine provides QT and DirectFB libraries to produce the video output for these ports, and the default video output is the regular LifeLine Web UI running on a stripped-down QT-based web browser. SDK applications can also produce their own video output to be displayed by these ports. LifeLine supports up to 8 different screens to be rendered at the same time, allowing the device to switch between them instantly. A new set of APIs is available to control the behavior of these screens. In order to use this feature, it is recommended to use an application set with at least two applications: The first application is used to produce the actual video output using the QT and DirectFB libraries. This will be referred to as the display application A second application is responsible for using the VGA APIs to register the display application with a specific screen. This will be referred to as the control application

To use multiple screens in the same application set, it is recommended that a separate application is associated with each screen.

Page 40 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

12.13.1

Compiling SDK applications with QT support

The LifeLine SDK provides the QT shared libraries to streamline the compilation of the QT-based binaries for SDK application. The Makefile template used for creating new SDK applications contains some commented-out variable definitions and the $(QT_APP_LOC)/$(QT_APP) target used for compiling the QT binary that produces the actual video output. To use this feature, you must uncomment the following lines, adding the name of the QT project and output binary file to the QT_APP and QT_PRO variables, respectively: ## ## Definitions for compiling QT application ## #QT_APP_LOC=<directory holding source files of the QT binary> #QT_APP=<name of the resulting QT binary file> #QT_PRO=<name of the QT project (.pro) file> #QT_MKSPECS=$(ARCH_DIR)/usr/qt/mkspecs #QT_MAKE=$(ARCH_DIR)/usr/qt/bin/qt-make You must also uncomment the contents of the QT-specific target: ###### Compile QT application #$(QT_APP_LOC)/$(QT_APP): () With this target in place, the regular compilation of the SDK application (make target=<architecture>) will automatically build the QT binary and place it in the root directory of the application. Since the QT binary may require some input parameters to run, it is recommended that a shell script is configured as the executable of the display application. This script will be invoked by the LifeLine application manager in the appropriate moment and should handle the execution of the QT binary with the necessary input parameters, such as: SampleQTApp --dfb:vt-num=8,session=7 qws display directfb Check the Books SDK sample application for an example on how to build the QT binary and invoke it using the shell script.

12.13.2

API interaction

In terms of SDK interaction and compilation, the control application is a regular application that uses the VGA LifeLine REST APIs to register one or more display applications with their respective screens to display video output. While the display applications are being registered, you may choose to mark one of them as active, using the state flag of the API, to cause it to remain visible as the currently active screen. The display applications themselves can switch the currently active screen when needed, or let the control application handle this. The operations described above utilize the following APIs: AppDisplays - Get a list of application displays. This API can be called by the control application to determine which screens are still available to use, to avoid conflicts with previously installed applications. AppDisplayModify Register a display application with a specific screen. This API is used by the control application to associate each display application with their respective screens. After this

Page 41 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

API is called, the referenced SDK application will be executed. You may also choose to activate this screen automatically after that. AppDisplaySwitch Switch the currently visible screen. This API may be used by the display application themselves to switch between different features, such as a configuration screen and a status screen, for example.

Check the complete REST API documentation for detailed usage information of these APIs.

12.13.3

Additional configurations

For better synchronization in the initialization of the control and display applications, it is recommended that: The display applications have their executable files configured with restartOnReboot=0, so that they are only invoked by the LifeLine Application Manager once they have been registered with the AppDisplayModify API. The control application has its executable configured with restartOnReboot=1, so that its executed immediately after installation, in order to be able to register the display applications. The control application waits until all display applications have been completely installed before proceeding with the registration procedure. This can be done using the Software API to check for installed applications.

12.14

User Visible Logs

The ApplicationLog LifeLine API allows SDK applications to add user-visible messages for important events to the list in the Event Log page of the LifeLine Web UI. User visible log messages should be localized and added to application.xml file, as part of the Localization list. These specific text entries must also contain a lognumber that will be displayed on the Event Log page next to the actual log message. In order to avoid conflicts with other text messages, this log number must be unique for each vendor. When SDK applications call the ApplicationLog API, they must provide: Their unique id, which is composed of the vendor id and application id, in the format <vendor>_<application id> A valid log number, associated with one of the text entries in their own application.xml file The level of the log message, such as normal, error or fatal, to indicate the severity of the message

12.15

Storing Application Data

The LifeLine SDK allows SDK applications to use a common share to store their internal data. An individual folder for each SDK application will be automatically created inside a share called ApplicationData. To use this feature, the value of the application/applicationdata attribute should be set to 1 on the application.xml file. This indicates that this application needs to have its own folder to store application data. The absolute path of the folder is passed as the second argument to the executable file of the application. The ApplicationData share will always be stored on the user partition, inside a volume that was indicated by the administrator of the device. The default volume, that is used before the administrator makes a selection, is the volume with the largest free space. The ApplicationData share will be automatically created when the first application that uses this feature is installed, or when the administrator chooses the volume where to store this share. This share is created without access permission to any user, so its contents wont be deleted or modified accidentally.

Page 42 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

Refer to the applicationdata sample SDK application for an example of how to receive the share path and use it to store data into the applications folder.

12.16

Custom validation during installation

The LifeLine SDK allows application sets to define custom validation steps to be executed during their installation. These steps may be used, for example, to check for the presence of necessary resources on the device. They are configured in the <applicationset>_upgrade.xml file, as Script entries, with the following attributes: File: Each of these steps consists of an executable binary file or script that must work independently of its current path. Shell, python and perl scripts are supported. Phase: This attribute defines whether the step is performed before any of the applications in the installation set are installed (Phase = 0) or after all of them have been completely installed (Phase = 1). ApplyMin / TooNew: These values specify the range of LifeLine firmware versions for which the step must be performed. ApplicationSetApplyMin / ApplicationSetTooNew: In case the application set is being upgraded, these values specify the range of versions of the currently installed application set for which the step must be performed.

The steps that are executed before the installation are able to abort the installation if needed. In order to do so, the executable must simply return a non-zero exit code. In case the installation is aborted, a custom error message may also be returned by the SoftwareInstall API and displayed to the user on the LifeLine Web UI. This optional message must be written to the standard output, localized to the current language selected by the user. The current language selection is passed to the executable as the $1 input argument. Refer to the sdksamples sample SDK application set for an example of how to create custom installation steps and how to receive the language argument in the executable files.

13 Application Best Practices

There are some best practices you should follow with the LifeLine SDK to improve application performance and provide a better user experience. The following are some recommendations to help you maximize the performance and maintainability of your SDK applications. Some of these recommendations are based on direct feedback from fellow SDK users and are lessons learned from the field.

13.1 Verify a Service or Feature Is Running Before Using It

As much as possible, your application should not assume any necessary LifeLine processes and/or features are already running. For example, if your application needs to perform any read/write activity or storage manipulation, your application must register for the FOLDER_UP event, which indicates the file system is up and ready. When you verify that necessary processes are running, you can prevent potential errors in your application.

13.2 No Share Creation Until a User Launches an Application

Applications must not create any Shares or add files on a device in which they are running, excluding any files added during installation, until the application is actually executed for the first time. Limiting Share creation until after an application starts reduces unwanted consumption of disk space and memory.

Page 43 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

13.3 Control Running State of the Application on the Applications Home Page
The home page of an SDK application should clearly inform to the user whether the application is running and enabled. Its important to note that the running state should not be si mply based on the state of the executable element of the application, for several reasons: The application may depend on more than one executable file or any other combination of factors to be considered enabled. The application may still be disabled, even though its executable file is running on the backend, especially when the executable file is used for handling REST API calls. According to section 6.4, the executable file on the backend might still be listening to incoming requests (and the application might still be enabled), even though it is not continuously running.

The home page should also allow users to enable and disable the application when necessary. For debugging purposes, it is possible to use the /manage/applications.html page to check the running state and start/stop the executable element of each individual SDK that is installed on the device.

13.4 Check Firmware Version for Compatibility

If an SDK application set is tied to a specific version of the LifeLine firmware (or a specific range of versions), its upgrade.xml file should contain the ApplyMin and or TooNew flags, described in section 14.1Error! Reference source not found., to make sure that it cant be installed on a device running an unsupported firmware version. If the application set is already installed when the device is upgraded to an unsupported version of the firmware, the Application Manager no longer starts the executable elements of the applications contained in the application set, independently of their configurations. However, the applications should be responsible for making sure they wont perform any operations that might have unexpected results on an unsupported version of the LifeLine firmware. In addition to that, the UI page of the application should make it clear for the user that the application has been disabled and that it must be updated to a newer version to continue to be used. Typical situations in which SDK applications are tied to specific firmware versions include: Use of LifeLine REST APIs introduced after version 1.0 of the APIs Use of deprecated LifeLine REST APIs Use of kernel modules, which are usually tightly coupled with an specific build of the Linux kernel Use of LifeLine features introduced after version 3.0 of the firmware Use of LifeLine features that were removed at some point

13.5 Store Application Data and User Metadata in the ApplicationData Share
SDK applications should not store any data in their installation directories, which reside in the system partition, with limited available space. Data should be stored on the user partitions, which can use all the available disk space on the device. This can be easily accomplished using ApplicationData feature described in section 12.15. This creates an individual folder for the application to store all its application data and user metadata in the ApplicationData share, which resides in the user partition. All applications should store their internal data in the ApplicationData share, to benefit from the following points: Having all application data centralized makes it easier to perform a backup of the settings and metadata of all installed applications at once.

Page 44 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd. -

CONFIDENTIAL AND PROPRIETARY

Since this share is created without access permission to users, its contents c ant be accidentally deleted or modified. LifeLine prevents this share from being deleted without warning. The application data is not deleted when the application is uninstalled, so the application can easily restore its state in a future installation.

If the administrator of the device moves the ApplicationData share to a different volume, all application data is automatically moved at once.

13.6 When to Use Callbacks for LifeLine APIs

SDK applications should use callbacks for LifeLine APIs whenever they must monitor and possibly block certain operations performed on the device, e.g.: Most applications are interested in being notified when the SoftwareUninstall API is called to know beforehand when they are about to be uninstalled. This allows applications to clean up their application data, interrupt critical operations in course, or simply block their removal until certain conditions are met. Once a share has been created to hold application data, the application should monitor calls to the ShareDelete API to prevent its data from being lost. An application might want to prevent the device from being rebooted or shut down while a critical operation is in course.

13.7 Combining Configuration Parameters for the Applications Executable

The configuration parameters for an applications executable file, described in section 6.2 and 6.4, can be combined in four different ways to achieve different results: 1. restartOnReboot=1 and runOnce=1: this is the default combination that allows the executable to be invoked once when the device restarts and: register all the required REST APIs, event callbacks, and LifeLine API callbacks start all required backend elements initialize or verify the application data in the ApplicationData share exit and wait to be invoked again when an incoming request must be handled.

All of this without having to remain running all the time or being continuously executed by the Application Manager. 2. restartOnReboot=0 and runOnce=1: this combination might be used by applications that perform all their operations through calls to cgi-bin scripts or LifeLine API calls and dont require any of the backend elements described above. 3. restartOnReboot=0 and runOnce=0: this combination is ideal for applications that must perform critical tasks that, once manually started from the UI, must run continuously, and automatically recover from crashes, until they are manually stopped from the UI. 4. restartOnReboot=1 and runOnce=0: this combination is suitable for executables that must be automatically started by the Application Manager and remain continuously running, automatically recovering from eventual crashes. This combination should only be used for executables with a long life cycle that dont need to be restarted often, except for crashes. Using this combination with executables that perform simple tasks and exit quickly (such as the cases described in item 1) is particularly harmful for the device performance, since the Application Manager is continuously busy restarting this executable.

Page 45 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

14 Upgrading an Application
SDK applications can be upgraded manually or automatically using an application set package (TGZ file) with a higher version number..

14.1 Upgrade Info XML File

Before creating an application set package, gather information for it using the Upgrade Info XML file. The information file includes the name of the application set package, its version, and the vendor that created it, among other data. The following is an example of an Upgrade Info XML file: <?xml version="1.0" encoding="utf-8" ?> <upgrade Type="4"> <Version ApplicationSet="AppSet1" ApplyMin="4.1" TooNew=4.2 ApplicationSetApplyMin="3.2" ApplicationSetTooNew="3.6" Id="ix2-ng" Version="3.4" /> <copyright>CompanyXYZ</copyright> <vendor>companyxyz</vendor> <File Name="appset1-3.4.tgz" Url= "http://www.companyxyz.com/ /> <depends Application="App0" Version="2.5" /> <depends Application="App2" Version="6.0" /> <Script File="pre_install.sh" ApplyMin="1.0" TooNew="7.0" Phase="0"/> <Script File="post_install.py" ApplicationSetApplyMin="1.0" ApplicationSetTooNew="2.0" Phase="1"/> </upgrade>

14.1.1 Parameter Explanations

<upgrade/type> <Version/ApplicationSet> <Version/ApplyMin> <Version/TooNew> <Version/ApplicationSetMinVer> <Version/ApplicationSetTooNew> <Version/Id> The type of the package. For SDK Application sets, this must always be "4". The unique id of the Application Set, as defined in the applicationSet.xml file. The minimum firmware version required to install this Application Set. A firmware version that is too new so that the Application Set cannot be installed. The minimum version of the Application Set that must be installed to apply this upgrade. An application set version that is too new so that the upgrade cannot be applied. The list of device models that are supported by this application set. The devices are specified by their "platform id" values, such as ix2-ng, h4c, and ix12. This is automatically filled out during compilation, according to the compilation target. The Application Set version that is installed by this package. The company that holds the Application Set copyright.

<Version/Version> <copyright>

Page 46 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

<vendor> <File/Encrypt> <File/Name> <File/Url> <File/size> <depends/application> <depends/version> <Script/File>

The Application Set vendor name. This should be the same name as the one in the Application Set configuration file. Flag to indicate whether the installation package is encrypted. The name of the application set installation package. The URL of the remote location containing the application set package. The size of the application set installation package in bytes. The ID of an application that must already be installed on the device in order to apply this upgrade. The version of the specified application that must already be installed on the device in order to apply this upgrade. The name of a file to be executed during the installation or upgrade of the application set. For more information, refer to section 12.16 The moment in which the file is executed. If 0, the file is executed before the installation or upgrade starts. If 1, the file is executed after all applications in the application set have been completely installed or upgraded. The minimum firmware version for which this file is executed. A firmware version that is too new so that the file is not executed. The minimum version of the Application Set that must be installed in the device to execute the file. An application set version that is too new so that the file is not executed.

<Script/Phase>

<Script/ApplyMin> <Script/TooNew <Script/ApplicationSetApplyMin> <Script/ApplicationSetTooNew>

In the example above, the Id is the identifier for the LenovoEMC ix2 device. The ApplicationSetApplyMin, ApplicationSetTooNew and depends parameters perform dependency checks during an application set upgrade. The ApplicationSetApplyMin parameter ensures that the specified version of the application set is already installed on the device before upgrading. Checking that the specified application set is installed guarantees backward compatibility between the upgrade version and the currently installed version. The ApplicationSetTooNew parameter ensures that the version of the application set that is already installed on the device is not newer than the specified value. This validation may be useful to prevent, among other issues, the downgrade of the application set in the device. The ApplyMin and TooNew parameters perform analogous checks for the firmware version of the device during an application set install or upgrade. These values are also taken into account when the firmware of the device is upgraded. If a Firmware that is equal to or higher than TooNew value is installed, the executables of all applications in the Application Set will no longer be started automatically by the LifeLine application manager. However, LifeLine does not automatically hide the icons for the unsupported applications nor does it prevent users from trying to interact with them. It is up to the applications to prevent further user interaction if the current firmware version is not supported. The depends parameter checks for application-level dependencies and verifies that the exact version of an application is available on the device. The application can be part of any installed application set. This

Page 47 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

tag is intended to provide a way to ensure that the upgraded application set remains fully compatible with other applications installed on the device.

Page 48 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

14.2 Manual Upgrade

Create an application set package (TGZ file) in your development directory. This package must include: Upgrade Info XML (named <application set name>_upgrade.xml) List of applications applicationSet.xml file

You can upgrade an application set either through the UI (refer to section 14.2.2) or through APIs (refer to section 14.2.3).

14.2.1 Including the Upgrade Information File in the TGZ File

Thehe Upgrade info XML file is automatically included in the TGZ package when the application set is compiled using the standard make call. Additionally, the application set version can also be set dynamically by using the parameter SET_VERSION= version. For example: $ make target=arm-ix2-ng SET_VERSION="2.0" generates the application set package for arm-ix2-ng targets, with the version 2.0 automatically set and including the upgrade.xml file in the package file.

14.2.2 Upgrading through the UI

Application set update information is listed in the update.html page

If you have the update package, you can just click on the Add software link in top left of page to upload the update package.

Page 49 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

Upload the update package to the device. This shows if the update is available to be applied.

Click Apply to apply the update.

14.2.3 Upgrade through the REST APIs

To upgrade through the REST APIs, follow this procedure. Refer to the API documentation for more details on the APIs. 1. Upload the application set package (TGZ file) that you created to a Share on a LenovoEMC device. For example, upload the package to the Documents Share using either samba or ftp. 2. Call the SoftwareInstall API and pass flags=uploadonly to initialize an upgrade process. 3. Call the Software API to see if the upgrade information for your application set is listed and ensure the availability parameter is correct. 4. Call the SoftwareApply API to apply the upgrade for your application set. 5. If you dont want to apply the package you uploaded, call the SoftwareDelete API to delete it.

Page 50 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

14.3 Automatic Upgrade

You can upgrade your application sets automatically using the autoupgrade process. When the autoupgrade process determines there are application sets to be upgraded, it indicates this in the Software Updates page in the UI and gives you the option to download and install the latest packages available. Create an application set package (TGZ file) in your development directory. This package must include: Upgrade Info XML (named upgrade.xml) List of applications applicationSet.xml file

Add the package to the URL defined in the File element of the upgrade.xml file. Make the upgrade.xml file available for download in the URL defined in the UpgradeInfo element of the applicationSet.xml file.

14.3.1 Automatic Upgrade Procedure

1. The autoupgrade process detects the upgrade.xml and automatically downloads it to a device. 2. Call the Software API to see if there is upgrade information for your application set that can be listed. 3. Call the SoftwareInstall API to download the upgrade package to a LenovoEMC NAS device. 4. Call the Software API to see if the upgrade information for your application set is listed and ensure the availability parameter is set to loaded. 5. Call the SoftwareApply API to apply the upgrade for your application set. 6. If you do not want to apply the upgrade package you uploaded, call the SoftwareDelete API to delete it.

Page 51 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

15 Migration from Previous Versions of the LifeLine SDK

Due to the many changes introduced in version 4.1 of the LifeLine firmware and SDK, including the change in Kernel version, SDK applications that had been created using any previous version of the LifeLine SDK are not guaranteed to work with the latest LifeLine firmware. Because of this, it is mandatory to upgrade all existing SDK applications to the 4.1 LifeLine SDK and recompile them to ensure full compatibility with the new LifeLine firmware. The following steps are recommended for upgrading applications and application sets from version 4.0 of the LifeLine SDK: Recreate your SDK application and application set projects in a new working directory with the same id and vendor values as used before. Copy all the source code and static files (UI pages and scripts, images, compiled libraries, CGI scripts) from the old project to the new project Dont copy the backup, rollback and remove scripts. The backup operation is now automatically performed by LifeLine during the upgrade of a previously installed application set. Dont copy the deb_control script. The installation packages for SDK applications are no longer based on the debian package format. You may copy the old application.xml and <applicationSet_id>.xml files on top of the new ones. Copy the contents of the <applicationSet_id>_upgrade.xml file to the new file, observing the following changes: The value of the upgrade/Type attribute for application sets is now 4. The Version/ApplyMin and Version/TooNew attributes, used to specify the supported versions of the application set, must be renamed to Version/ApplicationSetApplyMin and Version/ApplicationSetTooNew, respectively. The Version/FWMinVer and Version/FwTooNew attributes, used to specify the supported versions of the device firmware, must be renamed to Version/ApplyMin and Version/TooNew, respectively.

Copy only the customized parts of the old Makefile scripts (for both the application and application set projects) to the new files in the respective projects, observing the following changes: The Makefile for application sets has been completely rearranged to contain only the code that is specific for each application set. All common code and definitions were moved to the Makefile.in file: Removed "UPGRADE_TARGETS" definition Removed "PKG_LIST_FILE" and "PKG_LIST_FILE_FULL" definitions The "all" target now depends on "package-create" instead of "package" Removed all targets after "all" target, expect for ".PHONY" Moved the "include $(LLSDK_HOME)/Makefile.in" directive to be after the "all" target Replaced "package" with "package-create" in the ".PHONY" target definition

The Makefile for applications has been modified in specific points to remove the support for features that are no longer available: Removed variables for backup/rollback/remove scripts and all references to them Removed variable definition for "control" directory and all references to it Moved the "include $(LLSDK_HOME)/Makefile.in" directive to be after the "all" target Removed any o2 check_app ..." calls

Page 52 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

The "sdkapibld" target now depends on "app-create-dirs" Removed the "$(eval $(call CREATE_PACKAGE_TARGETS, <application id>, package))" call that existed before the "package" target Removed "deb_control" dependency from "package" target Replaced all "cp -rf" commands with "cp -rfp" Removed "install" target

With the constant evolution of the LifeLine REST APIs, existing APIs may be modified. Some of the possible changes include: new input parameters, changes to existing input parameters, changes to the return values, removal of existing input parameters and deprecated APIs. If you do not follow these changes, you may experience API calls to fail or unexpected values to be returned. It is important to check whether any of the LifeLine APIs used by your SDK application are affected. The complete list of affected APIs can be found in the Release Notes available as part of the SDK documentation.

Update the version of the CPipc and its header files in the application Makefile to 2.2. It is no longer necessary to add the upgrade parameter to the make call to build an upgrade package for your SDK application set. The upgrade.xml is always included by default now.

In addition to these basic steps, depending on the version of the LifeLine SDK from which your application or application set is being migrated, additional steps may be required, as described in the following sections.

15.1 Migrating to Version 4.1 from Any Version Before 4.0

To recompile any SDK application sets and applications created with version 3.2 or older of the SDK, the following modifications are required: Observe the new location for CGI scripts, indicated in section 8: UI pages, scripts and images are still placed in the <app-id>-www folder in the projects directory CGI scripts must be placed inside the cgi-bin directory, which now resides inside the applications www directory.

Individually copy each attribute value from the old application.xml, <applicationSet_id>.xml and <applicationSet_id>_upgrade.xml files to the new files, observing the changes below. Simply copypasting the entire XML files on top of the new ones may invalidate the process. All the URLs and relative paths specified in the application.xml file must now be defined as relative to the applications www directory. The setup element should not be present in the application.xml file unless the application is actually added to the setup category. Applications can no longer have multiple executables defined in their application.xml files. Applications that still require more than one executable to be controlled by LifeLines Application Manager should be divided into two or more applications with one executable per application. The upgrade/name element of the <applicationSet_id>_upgrade.xml is no longer needed. New placeholders are added to the URLs specified in the <applicationSet_id>.xml and <applicationSet_id>_upgrade.xml files to facilitate the automatic generation of different URLs for each SDK target.

The backend functions that are registered to handle REST APIs exposed by the SDK application must now receive the incoming parameters in the form of a hash table, instead of the fixed-order list as before. All such functions must be updated according to the details in section 12.6.

Page 53 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

It is no longer necessary to keep the executable of an SDK application locked in an infinite loop to handle incoming IPC calls. This was usually done when the executable registered backend functions as handlers for REST APIs exposed by the SDK application. The executable of an SDK application is now automatically started by the Application Manager when it needs to handle an incoming IPC call. Refer to section 6.4 for details on the new interaction model between the Application Manager and the executables from SDK applications.

The Application Manager page no longer displays the running state of the SDK application sets, nor allows users to start or stop them. Since the real running state of an application might depend on other factors and the enable/disable operation might require more changes than simply stopping one specific executable file, SDK applications must display their running state and allow users to enable or disable the application through their own UI pages. Refer to section 13.3 for additional details.

The CPipc library and related header files are now versioned. This version number matches the version number of the LifeLine REST APIs. The names of the binary file of the CPipc library and the directory holding its related header files now carry the version number of the library. The Makefile of existing SDK applications must be updated to include this version number when linking the CPipc library and when including the directory of the related header files. Refer to section 12.1.2 for details.

The change above allows SDK applications to link with specific versions of the CPipc library and use it to make direct calls to LifeLine APIs. Refer to section 12.10 12.10 for details. The cpIpcStartListener function takes one input parameter, name, that must consist of the vendor name and the application id, in the form <vendor>_<app_id>. Refer to section 12.1.2 for details.

15.2 Migrating to Version 4.1 from Any Version Before 3.2

To recompile any SDK application set and applications created with version 3.1 or older of the SDK, the following modifications are required: Update the APP_LDFLAGS line in the application's Makefile to include the soup-2.4 lib, as described in section 12.1.2. Replace existing calls to functions in Event.h by calls into the equivalent REST APIs, as described in section 12.1.2: cpEventRegister - CallbackEventRegister cpEventDeregister CallbackEventDeregister cpEventBroadcast and cpEventLocal EventSend API

Add calls to cpIpcInit and cpIpcStartListener before using any of the functions in CPipc.h, as described in section 12.1.2.1. Remove any references to CP.h, Event.h, or any other header file that is no longer included in the LifeLine SDK. The available header files are located at: $LLSDK_HOME/<architecture>/usr/include/CP.

Remove any references to LifeLine functions that are not exposed in one of the header files included in the current version of the LifeLine SDK. The File/URL attribute must be replaced by the File/Url attribute, containing the URL of the remote directory that holds the TGZ installation package without the filename.

Page 54 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

15.3 Migrating to version 4.1 from versions 3.2 and 3.3

Replace existing calls to event-related functions in CPipc.h by calls into the equivalent REST APIs, as described in section 12.2: cpIpcRegisterEventHandler CallbackEventRegister cpIpcCleanup CallbackEventDeregister

16 Deleting Applications during an Upgrade

To delete an application during the application set upgrade process, add the "delete" attribute to the application's entry in the applicationSet.xml file that is part of the upgrade installation package: <application id="sampleAppId2" delete="1">

17 Debugging Applications
Developers can debug SDK applications using the GDB debugger on the target device. Compile your SDK application with appropriate debug options for debugging the application.

18 Recommended Testing Tools

To test performance and measurements with your application running on the LifeLine device, the following tools are recommended: iometer (http://www.iometer.org/) Iometer is an I/O subsystem measurement and characterization tool for single and clustered systems. Intel NAS Performance Toolkit (http://www.intel.com/ ) The Intel NAS Performance Toolkit (Intel NASPT) is a file system exerciser and analysis tool designed to enable performance comparisons between network attached storage (NAS) devices. While NASPT runs on a 32-bit client version of Windows XP or Windows Vista, the target NAS device may run any operating system.

19 Getting Help
The LenovoEMC LifeLine Developer community offers forums, blogs, and documentation for the LifeLine SDK. Refer to http://developer.lifelineapps.com.

Page 55 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

20 Appendix A Sample Code

The appendix provides sample code.

20.1 REST and XMLRPC Examples

To make REST calls, use the following format: http://<device_ip>/cp/api_name?v=1&arg1=val1&arg2=val2 where api_name is the API to be called v is the API version used for the call arg1, arg2, are parameters, and val1, val2, are their values

20.2 REST Call with No Parameters

http://<device_ip>/cp/SystemInfo?v=1 is how SystemInfo API is called. It does not take any parameters and returns a SystemInfo structure when the call is made using a browser. {"id":"VMware-56 4d 60 bd d7 b3 07 c3-d0 54 34 59 25 c5 eb 28", "ip":"192.168.221.194","clientmin":13, "bios":"6.00", "description":"LenovoEMC Virtual Machine", "clientver":13, "name":"storage", "model":"LenovoEMC Virtual Machine", "severity":"warning", "version":"2.7.3.3 67589 2010-07-14 08:06 kothal", "flags":""}

Page 56 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

20.3 REST Call with Parameters 20.3.1 Shares API

This API may be called with different numbers of parameters, since all its parameters are optional: http:// <device_ip>/cp/Shares?v=1&sortby=name&max=0&start=0 or http:// <device_ip>/cp/Shares?v=1 The first call shows how parameters are passed. It returns: {"start":0, "left":0, "items":[ {"access":"readwrite","security":"none","activefolder": {"status":"disabled", "pos":0,"type":"torrent","description":"Torrent file transfer."}"name":"Backups","flags":"autogrow|mediaserver","imgurl":""}, {"access":"readwrite","security":"none","activefolder": {"status":"disabled","pos":0,"type":"torrent","description":"Torrent file transfer."},"name":"Documents","flags":"contentsearch|autogrow|mediaserver","imgurl":""} , {"access":"readwrite","security":"none","activefolder": {"status":"disabled","pos":0,"type":"torrent","description":"Torrent file transfer."},"name":"Pictures","flags":"contentsearch|autogrow|mediaserver","imgurl":""} ]}

Page 57 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

20.3.2 SecurityEnable API

This call is used to enable security on the device and configure the requirements for using encrypted connections (HTTPS): http://<device_ip>/cp/SecurityEnable?v=1.5&security:login=admin& security:password=admin&security:fullname=Sample administrator& security:encryptlocal=none&security:encryptremote=always If the call is successful, only an empty string is returned.

20.3.3 UserCreate API

This call is used to create regular users or administrator users to access the device via the LifeLine Web Interface or REST API calls. To create users, you must have security enabled on the device. https://<device_ip>/cp/UserCreate?v=1.5&user:login=user&user:password=1234& user:name=Sample user&user:flags=addshare&quota=-1 If the call is successful, only an empty string is returned.

20.4 REST Call with Struct as a Parameter

The ShareCreate API is called with: http://<device_ip>/cp/ShareCreate?v=1&share:name=TestNewShare&share:security= write&share:flags=mediaserver" This call takes the struct share as a parameter; and struct share contains fields name, pool, volume, security and flags. If the call is successful, only an empty string is returned.

20.5 Error Information

The REST API returns error information if a call is invalid or not supported. Error information is returned in error struct. For example: {"error":{"code":"65542","text":"Security must be enabled in order to apply the requested settings.","field":""}}

20.6 To Call Methods Using XML-RPC

XML-RPC can be tested with any client. The following calls are made using python. Calls are in the following format: $python >>>import xmlrpclib >>>server = xmlrpclib.ServerProxy("http://<device_ip>/cprpc/") >>>i=server. api_name("1",val1, val2,..) >>>i Where api_name is the api to be called. Val1, val2 are values of the arguments in order. If a value is null, 0 is used instead of blank space or null.

Page 58 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

20.7 Example XML-RPC call with No Parameters

$python >>>import xmlrpclib >>>server = xmlrpclib.ServerProxy("http://<device_ip>/cprpc/")>>>i=server. SystemInfo("1") >>>i Returns output as above.

20.8 Example XML-RPC call with Parameters

$python >>>import xmlrpclib >>>server = xmlrpclib.ServerProxy("http://<device_ip>/cprpc/") >>>i=server. UserExists("1", "login") >>>i Returns false/true

20.9 Example XML-RPC call with Struct as a Parameter

UserCreate API takes struct user as a parameter. $python >>>import xmlrpclib >>>server = xmlrpclib.ServerProxy("http://<device_ip>/cprpc/") >>> user = {'login':'testingUser', 'name':'Test User', 'password':'1234', 'uid':'9878', 'flags':'clearpassword', 'quota:1000} >>> server.UserCreate("1",user)

20.10 Error Information

An XML-RPC call prints an error message on the console if a call is invalid, not supported, or has bad parameters.

20.11 Sample Applications

The LifeLine SDK contains a sample application set (sdksamples), which is composed of several example applications. To build, point LLSDK_HOME to the directory where you installed the SDK, change to the samples/sdksamples directory and run: make target=<architecture> Where "architecture" is one of the supported architectures. Next, install the TGZ file in the vmware or device, using the Application Manager page of the LifeLine web UI. After installation, the sample applications can be accessed through their icons on the LifeLine Web UI

Page 59 of 60

4.1.2

LenovoEMC LifeLine SDK Guide

 2013 LenovoEMC, Ltd.

CONFIDENTIAL AND PROPRIETARY

The page of each sample application contains an explanation of the features being demonstrated by it and instructions on how to use them.

21 Appendix B SDK Utilities

This appendix provides information on utilities included with the LifeLine SDK.

21.1 SDK Application Utility Program

Use the cp-appmd to install, remove, and list a single application. The following are descriptions of the utility program commands. /usr/local/cp-utils/cp-appmd list Lists all the installed applications. /usr/local/cp-utils/cp-appmd install <path> Installs a new application, where path is an absolute path to tgz file on a LenovoEMC NAS device. Also, it displays a message "Installing file_name.tgz OK". /usr/local/cp-utils/cp-appmd start <application> Starts an application and displays a message "Starting Application_name OK". /usr/local/cp-utils/cp-appmd stop <application> Stops an application and displays a message "Stopping Application_name OK". /usr/local/cp-utils/cp-appmd remove <application> Removes an application and displays a message "Removing package Application-name OK".

22 Appendix C Installing Partners Applications at Manufacturing

LenovoEMC allows partner applications to be installed at manufacturing time. Contact LenovoEMC for more details.

Page 60 of 60

4.1.2

LenovoEMC LifeLine SDK Guide