Update documentation

modules/util-agentlog.js

@@ -15,11 +15,21 @@ limitations under the License.
 */
 
 
+// 
+// This is a helper module for parsing and enumerating Mesh Agent log entries
+//
+
+//
+// This function parses a log entry, and and pushes each parsed log entry into the results array
+//
 function parseLine(entry)
 {
+
+    // Use a regex to parse the log entry
     var test = entry.match(/^\[.*M\]/);
     if (test == null)
     {
+        // Use a regex to find a windows crash entry
         test = entry.match(/\[.+ => .+:[0-9]+\]/);
         if (test != null)
         {
@@ -34,6 +44,7 @@ function parseLine(entry)
         }
         else
         {
+            // On linux, use a regex to determine if a crash entry contains symbol info
             test = entry.match(/^[\.\/].+\(\) \[0x[0-9a-fA-F]+\]$/);
             if (test != null)
             {
@@ -47,6 +58,7 @@ function parseLine(entry)
             }
             else
             {
+                // use a regex to try to finx the CrashID on linux
                 test = entry.match(/^\[.+_[0-9a-fA-F]{16}\]$/);
                 if(test!=null)
                 {
@@ -56,6 +68,7 @@ function parseLine(entry)
                 }
             }
 
+            // Use a regex to find the crash entry
             test = entry.match(/(?!^=>)\/+.+:[0-9]+$/);
             if(test!=null)
             {
@@ -69,11 +82,13 @@ function parseLine(entry)
     }
     test = test[0];
 
+    // Parse out the timestamp
     var dd = test.substring(1, test.length -1);
     var c = dd.split(' ');
     var t = c[1].split(':');
     if (c[2] == 'PM') { t[0] = parseInt(t[0]) + 12; if (t[0] == 24) { t[0] = 0; } }
 
+    // Parse out the message and the agent hash
     var d = Date.parse(c[0] + 'T' + t.join(':'));
     var msg = entry.substring(test.length).trim();
     var hash = msg.match(/^\[[0-9a-fA-F]{16}\]/);
@@ -107,6 +122,10 @@ function parseLine(entry)
     this.results.push(log);
 }
 
+//
+// This function will accumulate a raw data read from the file system, and attempt
+// to parse the entries line by line
+//
 function readLog_data(buffer)
 {
     var lines = buffer.toString();
@@ -130,6 +149,10 @@ function readLog_data(buffer)
     }
 }
 
+//
+// This function will attempt to read the Mesh Agent log specified by 'path'
+// and return an array of log entries
+//
 function readLogEx(path)
 {
     var ret = [];
@@ -138,7 +161,7 @@ function readLogEx(path)
         var s = require('fs').createReadStream(path);
         s.buffered = null;
         s.results = ret;
-        s.on('data', readLog_data);
+        s.on('data', readLog_data); 
         s.resume();
         if (s.buffered != null) { readLog_data.call(s, s.buffered); s.buffered = null; }
         s.removeAllListeners('data');
@@ -151,6 +174,10 @@ function readLogEx(path)
     return (ret);
 }
 
+//
+// This function will attempt to read the Mesh Agent log specified by 'path'
+// and return an array of log entries. 'criteria' can be the number of log entries to fetch, or a timestamp of the oldest entry to fetch
+//
 function readLog(criteria, path)
 {
     var objects = readLogEx(path == null ? (process.execPath.split('.exe').join('') + '.log') : path);

modules/win-bcd.js

@@ -14,6 +14,14 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+//
+// win-bcd interacts with Windows BCD to be able to modify Safe Mode related settings
+//
+
+
+//
+// This function uses the Windows System Utility 'bcdedit' to fetch metadata about the bootloader configuration
+//
 function getKeys()
 {
     var ret = {};
@@ -25,6 +33,9 @@ function getKeys()
     var lines = child.stdout.str.trim().split('\r\n');
     lines.shift(); lines.shift();
 
+    //
+    // Enumerate each line entry, and parse out the key/value pair
+    //
     for (var i in lines)
     {
         var tokens = lines[i].split(' ');
@@ -34,10 +45,18 @@ function getKeys()
     }
     return (ret);
 }
+
+//
+// Returns the value associated with the specified key
+//
 function getKey(key)
 {
     return (this.getKeys()[key]);
 }
+
+//
+// Using the Windows System Utility 'bcdedit', set a key/value to the current bootloader configuration
+//
 function setKey(key, value)
 {
     var child = require('child_process').execFile(process.env['windir'] + "\\System32\\bcdedit.exe", ['bcdedit', '/set', '{current}', key, value]);
@@ -45,6 +64,10 @@ function setKey(key, value)
     child.stderr.on('data', function () { });
     child.waitExit();
 }
+
+//
+// Using the Windows System Utility 'bcdedit', delete a key/value pair from the current bootloader configuration
+//
 function deleteKey(key)
 {
     var child = require('child_process').execFile(process.env['windir'] + "\\System32\\bcdedit.exe", ['bcdedit', '/deletevalue', '{current}', key]);
@@ -53,10 +76,17 @@ function deleteKey(key)
     child.waitExit();
 }
 
+//
+// Add the specified service name, to Window's list of services allowed to run in SafeMode with Networking
+//
 function enableSafeModeService(serviceName)
 {
     require('win-registry').WriteKey(require('win-registry').HKEY.LocalMachine, 'SYSTEM\\CurrentControlSet\\Control\\Safeboot\\Network\\' + serviceName, null, 'Service');
 }
+
+//
+// Query if the specified service name is allowed to run in Safe Mode
+//
 function isSafeModeService(serviceName)
 {
     var reg = require('win-registry');
@@ -64,6 +94,10 @@ function isSafeModeService(serviceName)
     try { key = reg.QueryKey(reg.HKEY.LocalMachine, 'SYSTEM\\CurrentControlSet\\Control\\Safeboot\\Network\\' + serviceName); } catch (qke) { }
     return (key.default == 'Service');
 }
+
+//
+// Remove the specified service from the allowed list of services that can run in Safe Mode
+//
 function disableSafeModeService(serviceName)
 {
     try
@@ -75,6 +109,9 @@ function disableSafeModeService(serviceName)
     }
 }
 
+//
+// Use the windows system utility, 'shutdown' to restart the PC immediately
+//
 function restart(delay)
 {
     var child = require('child_process').execFile(process.env['windir'] + "\\System32\\shutdown.exe", ['shutdown', '/r', '/t', delay!=null?delay.toString():'0']);
@@ -85,6 +122,9 @@ function restart(delay)
 
 if (require('_GenericMarshal').PointerSize == 4 && require('os').arch() == 'x64')
 {
+    //
+    // 32 bit agent running on 64 bit windows, we do not expose BCD functions, because bcdedit does not work from a 32 bit process on 64 bit windows
+    //
     module.exports =
     {
         enableSafeModeService: enableSafeModeService,
@@ -99,6 +139,9 @@ else
             disableSafeModeService: disableSafeModeService, getKey: getKey, restart: restart, isSafeModeService: isSafeModeService
         };
 
+    //
+    // Query what the next boot mode is currently set to... NORMAL, SAFEMODE, or SAFEMODE w/Networking
+    //
     Object.defineProperty(module.exports, "bootMode",
         {
             get: function ()