_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
_/                                                                _/
_/   LARA web scripting api documentation                         _/
_/   based on firmware version 03.04.02                           _/
_/                                                                _/
_/   ATTENTION: this document and the interfaces it describes     _/ 
_/              are subject to change without notice!!!           _/
_/                                                                _/
_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/

/*********************
 * General information 
 */

This document describes the ASP functions which may be of interest to
OEMize the web pages for LARA or LARA eco systems. As a general rule, leave the
code as it exists in the original pages and only change the look of it, so this
documentation is primarily intended for information about whats going on.

ASP code/functions is enclosed in <% %>.

Availability describes the type of product the function is available
on. Possible values are "lara" and "rc1" (means lara eco). Where availability is
not mentioned, all devices support this function.

/****************************
 * LARA related asp-functions
 */
 
/**
 * Function: write(String text)
 * usage: <% write("text"); %>
 * desc: Used to write html code dynamically into asp pages.
 */

/**
 * Function: writeEsc(String text)
 * usage: <% writeEsc("text"); %>
 * desc: Same as write but escapes some characters that are reserved in ASP.
 *       ( used to write plain text instead of html code )
 */
  
/**
 * Function: skipStart
 * usage: <% if (_confirm != "yes") { skipStart(); } %>
 * desc: Skip HTML output until skipEnd is called.
 *       skipStart/skipEnd are recursive, means skipEnd has
 *       to be called as many times as skipStart before to enable
 *       the output again
 */
  
/**
 * Function: skipEnd
 * usage: <% if (_confirm != "yes") { skipEnd(); } %>
 * desc: Enables HTML output again.
 *       skipStart/skipEnd are recursive, means skipEnd has
 *       to be called as many times as skipStart before to enable
 *       the output again
 */

/**
 * Function: createAppletID
 * usage:  APPLET_ID="<% writeEsc(createAppletID()); %>"
 * desc: Return an unique ID for the Remote Console Applet.
 *       Used in the startup page "title_app.asp" for the applet as
 *       an applet parameter.
 */
  
/**
 * Function: link(String link)
 * usage: <a href="<% write(link('um.asp')); %>...
 * desc: If you need to write html link targets to pages on the device, enclose
 *       them in this function. This is intended for future use with 
 *       central management and not currently necessary for a single
 *       device but doesn't do any harm either.
 */
 
/**
 * Function: rfbport
 * usage:  PORT="<% writeEsc(rfbport()); %>"
 * desc: Returns the current RFB port to connect to, needed for the applet
 *       "title_app.asp" as a parameter.
 */

/**
 * Function: getResponseMsg
 * usage: <% write(getResponseMsg()); %>
 * desc: Returns the response message (warnings, errors ...) to form actions.
 *       One such call is needed on each formular.
 */

/**
 * Function: writeConnectedUsers
 * usage:  <td align="left" class="normal"><% writeConnectedUsers(); %></td>
 * desc: Write a list of all connected users in the following style:
 *       Used on the board.asp "Maintenance" page.
 *      <table border="0" cellpadding="2" cellspacing="0">
 *        <tr>
 *           <td><div class="normal">super</td>
 *           <td><div class="normal">(192.168.1.44)</td>
 *           <td><div class="normal"></td>
 *           <td><div class="normal">4 min idle</td>
 *        </tr>
 *      </table>
 */

/**
 * Function: getVarByIdx(String param_name, Integer index) 
 * usage: _name = getVarByIdx("ECG_kvm_portname", i)
 * desc: Returns a multipart variable by it's index
 *       Multipart variables are arrays of values of the same type,
 *       indexed from 0.
 */

/**
 * Function: htmlEsc(String text)
 * usage:  htmlEsc(_powername)
 * desc: Write code into asp pages and escape characters that are reserved in HTML.
 *       ( used to write plain text to the page )
 */

/**
 * Function: getInternalVar(String internal_var)
 * usage: PROTOCOL_VERSION="<% writeEsc(getInternalVar("rfb_version")); %>"
 * desc: Returns a internal variable, currently available:
 *       rfb_version    - version of the RFB protocol supported by the server
 *                        in the format xx.yy, xx=major version, yy=minor
 *                        version
 *       dyndns_default - get dyndns server, currently www.dyndns.org
 *       vendor_homepage- homepage URL of the vendor of the device
 *       special_color  - get a special color from the current stylesheet
 *                        currently: telnetbg, telnetfg - colors for the telnet
 *                        applet. Submit the name of the color as second parameter.
 *	 screenshot_info- get info about the remote console preview screenshot
 *                        (currently "width" or "height"), submit the type as 
 *                        second parameter.
 */

/**
 * Function: getKvmActivePort
 * usage: _active_port = getKvmActivePort();
 * desc: Returns the active KVM Port of a connected KVM switch.
 *       Will be always 0 for LARA eco devices.
 */

/**
 * Function: getKvmMaxPortCount
 * usage: _max_count = getKvmMaxPortCount();
 * desc: Returns the maximum number of KVM ports the device supports.
 *       Will be always 1 for LARA eco devices.
 */

/**
 * Function: getKvmPortCount
 * usage: _count = getKvmPortCount();
 * desc: Returns the current number of KVM ports the device is configured with.
 *       Will be always 1 for LARA eco devices.
 */

/**
 * Function: rand
 * usage: _random = rand();
 * desc: Returns a random 32-bit decimal number (c-type long)
 */

/**
 * Function: getHardwareRev
 * usage: _hw_id = getHardwareRev();
 * desc: Returns a 2 digit hexadecimal number describing the hardware
 *       revision of the board.
 */

/**
 * Function: getKvmCanSwitchToPort(Integer portnr)
 * Availability: lara
 * usage: _can_switch = getKvmCanSwitchToPort(0);
 * desc: Returns '1' if a switching to this KVM port is possible, '0'
 *	 otherwise. 
 */

/**
 * Function: getPortnameFromIndex(Integer portnr)
 * Availability: lara
 * usage: _can_switch = getPortnameFromIndex(0);
 * desc: Returns the (user given) name for the KVM port with this number.
 */

/**
 * Function: writeFile(String html_file)
 * Availability: lara
 * usage: <% writeFile("custom.html"); %>
 * desc: Insert custom html code into asp page.
 */  

/**
 * Function: getFWInfo(String fw_pos, String info)
 * usage: _build_nr = getFWInfo("running", "build_nr");
 * param fw_pos: "running", "uploaded"
 * param info: "version", "build_nr", "tag", "all"
 * desc: Returns several infos about running or uploaded firmware.
 */

/**
 * Function: boardName
 * usage: <% _boardname = boardName(); %>
 * desc: Get the name of the device ("LARA eco" or similar)
 */  

/***************************************
 * Keyboard/Mouse related functions
 */

/**
 * Function: kmResetIsImplemented
 * usage: _reset_possible = kmResetIsImplemented();
 * desc: Return '1' if the currently active combination of mouse
 *       and keyboard devices supports a "Reset" functions, '0' 
 *       otherwise
 */

/**
 * Function: kmIsUsbPossible
 * usage: _usb_possible = kmIsUsbPossible();
 * desc: Return '1' if the device supports USB keyboard/mouse,
 *       '0' otherwise
 */

/**
 * Function: kmIsUsbActive
 * usage: _usb_active = kmIsUsbActive();
 * desc: Return '1' if USB keyboard/mouse emulation is active,
 *       '0' otherwise
 */

/***************************************
 * ACL/user management related functions
 */
  
/**
 * Function: aclHasPermission(String perm_name, String perm_type)
 * Availability: lara, rc1
 * usage: __skip = aclHasPermission("excl", "allow") != "yes";
 * desc: Returns yes or no dependend on the given permission
 *       List of available objects with permissions 
 *      'acl'	        => 'User/Group Permissions'
 *		'perms' => 'view', 'change'	
 *              used in => 'acl.asp'
 *              Avail   => lara
 *      'cert'	        => 'SSL Certificate Management'
 *		'perms' => 'allow'
 *              used in => 'security.asp'
 *              Avail   => rc1
 *	'events_ipmi'	=> 'Event Log via IPMI'
 *		'perms' => 'view', 'change'	
 *              used in => 'navigate.asp'				
 *              Avail   => lara
 *      'fw'		=> 'Firmware Update'
 *	        'perms' => 'allow'	
 *              used in => 'board.asp'		 
 *	'ipmi_s'	=> 'IPMI Settings'
 *		'perms' => 'view', 'change'
 *              used in => 'navigate.asp'
 *              Avail   => lara
 *	'isdn_s'	=> 'ISDN Settings'
 *		'perms' => 'view', 'change'
 *              used in => 'navigate.asp'
 *              Avail   => lara
 *	'km_s'		=> 'Keyboard/Mouse Settings'
 *		'perms' => 'view', 'change'
 *              used in => 'navigate.asp'
 *              Avail   => lara
 *	'kvm_s'		=> 'KVM Settings'
 *		'perms' => 'view', 'change'
 *              used in => 'home2.asp'
 *                         'kvm.asp'
 *                         'navigate.asp'
 *              Avail   => lara
 *	'modem_s'	=> 'Serial Settings'
 *		'perms' => 'view', 'change'
 *              used in => 'navigate.asp'
 *              Avail   => lara
 *	'net_s'		=> 'Network Settings'
 *		'perms' => 'view', 'change'
 *              used in => 'navigate.asp'
 *	'pc'		=> 'Server Power Control'
 *		'perms' => 'allow'
 *              used in => 'home2.asp'                           
 *                         'navigate.asp'
 *              Avail   => lara
 *	'pc_s'		=> 'Power Control Settings'
 *		'perms' => 'view', 'change'
 *              used in => 'navigate.asp'
 *              Avail   => lara
 *	'rc'		=> 'Remote Console Access'
 *		'perms' => 'allow'
 *              used in => 'home2.asp'                           
 *                         'navigate.asp'
 *	'rc_s_enc'	=> 'RC settings (Encoding)'
 *		'perms' => 'view', 'change'
 *              used in => 'rc_settings.asp'
 *	'rc_s_hk'	=> 'RC settings (Hotkeys)'
 *		'perms' => 'view', 'change'
 *              used in => 'rc_settings.asp'
 *	'rc_s_mm'	=> 'RC settings (Monitor Mode)'
 *		'perms' => 'view', 'change'
 *              used in => 'rc_settings.asp'
 *                         'title_app.asp'
 *	'reset'		=> 'Board Reset'
 *		'perms' => 'allow'
 *              used in => 'board.asp'
 *                         'video_custom.asp'
 *	'sec_s'		=> 'Security Settings'
 *		'perms' => 'view', 'change'
 *              used in => 'navigate.asp'
 *              Avail   => lara
 *	'serial_s'	=> 'Serial Settings'
 *		'perms' => 'view', 'change'
 *              used in => 'navigate.asp'
 *	'snmp_s'	=> 'SNMP Settings'
 *		'perms' => 'view', 'change'
 *              used in => 'navigate.asp'
 *              Avail   => lara
 *	'status_ipmi'	=> 'Server Status via IPMI'
 *		'perms' => 'view', 'change'
 *              used in => 'navigate.asp'
 *                         'status_ipmi.asp'
 *              Avail   => lara
 *	'um'		=> 'User/Group Management'
 *  	        'perms' => 'view', 'change'
 *              used in => 'navigate.asp'
 *                         'um.asp'
 */ 
  
/**
 * Function: aclInitAllObjects
 * Availability: lara
 * usage: <% aclInitAllObjects(); %>
 * desc: Initialize variable list with all permission objects 
 *       which can be read as 'all_objects_%u' were "all_objects_cnt"
 *       contains the number of objects. Each var contains the permission
 *       string id which can be used for aclHasPermission or aclGetLongObjectName.
 */ 

/**
 * Function: aclGetLongObjectName(String object_name)
 * Availability: lara
 * usage: write('    <div class="bold">', aclGetLongObjectName(o), '</div>\n'...
 * desc: Returns the real name of a permission object, like
 *       'SSL Certificate Management' for 'cert'
 *       see aclHasPermission for all available permission ids
 */ 
 
/**
 * Function: aclInitAllObjectPerms(String object_name)
 * Availability: lara
 * usage: aclInitAllObjectPerms(o);
 * desc: with the given permission object, these function initialize a list
 *       with all permissions for this object ( like 'allow' or 'deny' )
 *       after a call to aclInitAllObjects, the following web vars are set, 
 *       appropriate to the current perission object:
 *          "p_object_perm"
 *          "p_object_color"
 *	    
 *          "p_effective_perm"
 *          "p_effective_color"
 *	    
 *          "p_inherited_perm"
 *          "p_inherited_color"
 *       see aclHasPermission for a list of all permission ids
 */

/**
 * Function: umInitAllPrincipals(String type)
 * usage:  umInitAllPrincipals("users");
 * param type: "users", "groups", "principals" (contains users and groups)
 * desc: Set web vars in form of user_%u, groups_%u, ... with matching *_cnt var.
 */  
  
/**
 * Function: umInitMemberOf
 * usage: umInitMemberOf();
 * desc: Create a list of groups where the current active user is a member of.
 *       accessible via "member_of_%u" and "member_of_cnt"
 */  
 
/**
 * Function: umAmIroot
 * usage: __skip = !umAmIroot();
 * desc: Returns '1' if the current active user is super user or '0' if not.
 */

/**
 * Function: umTUIsRoot
 * usage: __skip = !umTUIsRoot();
 * desc: Returns '1' if the current target user is super user, '0'
 *       otherwise.
 */

/***************************************
 * Certificate related functions
 */

/**
 * Function: caInit
 * usage: <% caInit(); %>
 * desc: Initialize certificate form, only done once in ca.asp
 */  
 
/**
 * Function: certGetCSRInfo
 * usage: <% _csr_info = certGetCSRInfo(); %>
 * desc: Returns information about current uploaded certificate.
 */  
  
/***************************************
 * ISDN related functions
 */

/**
 * Function: ISDNSupported
 * Availability: lara
 * usage:  isdn_support = ISDNSupported(); 
 * desc: If (ISDNSupported != "") ISDN is supported, otherwise not.
 */  

/**
 * Function: ISDNLastNumber(String channel, String type)
 * Availability: lara
 * usage: _number = ISDNLastNumber("0", "caller");
 * desc: Returns the last called/calling number for a specific channel.
 *       channel may be "0" or "1", type may be "caller" or "called".
 */  

/***************************************
 * Direct connect link related functions
 */
 
/**
 * Function: GetLinkFormCode(Integer id)
 * usage: _link = GetLinkFormCode(0);
 * desc: Return the form code (link including the image) for an entry
 *       for the direct connect link feature. The number of connect links
 *       is set to the variable "connect_link_count" on the home2.asp and
 *       r1_home2.asp forms.
 */

/**
 * Function: GetLinkName(Integer id)
 * usage: _link = GetLinkFormCode(0);
 * desc: Return the link name for an entry for the direct connect link
 *       feature. The number of connect links is set to the variable
 *       "connect_link_count" on the home2.asp and r1_home2.asp forms.
 */  


/***************************************
 * Host info functions
 */

/**
 * Function: getHostInfo(String info)
 * usage: _power = getHostInfo("power");
 * param info: "power"
 * desc: Returns info about host status 
 *      ( only power status is supported )
 */
 
/**
 * Function: ipmiGetSensorData
 * Availability: lara
 * usage: ipmiGetSensorData();
 * desc: Triggers the LARA device to read the SDR repository from host system which contains 
 *       required sensor data ( fan speed, temperature, voltanges ). Variables will be initialized 
 *       with this values and can be read from asp page.
 *       Vars are in form of: <sensortype>_<datatype>_<number> e.g. voltage_min_crit_1
 *       ( these are multipart vars so they can be accessed with 'getVarByIdx("voltage_min_crit", i)' )
 *        sensortypes:  fan                
 *                      voltage
 *                      temp 
 *        datatypes:    id
 *                      owner
 *                      name
 *                      status
 *                      value
 *                      min_crit
 *                      min
 *                      max
 *                      max_crit
 *        number is a ordinal number and the maximum is given in 'fan_id_cnt', 'temp_id_cnt' and 'voltage_id_cnt'
 *        ( some sensors doesn't support all datatypes so they return a null string )
 *
 */  
 