From e56b452dc52798aea290b2d3fee1c9ed130a39b4 Mon Sep 17 00:00:00 2001
From: JJ Fullmer <jfullmer@arrowheaddental.com>
Date: Tue, 23 Aug 2022 11:58:21 -0600
Subject: [PATCH] Add more documentation to get-lastimagetime

---
 FogApi/Public/Get-LastImageTime.ps1 | 45 +++++++++++++++++++++++++----
 1 file changed, 39 insertions(+), 6 deletions(-)

diff --git a/FogApi/Public/Get-LastImageTime.ps1 b/FogApi/Public/Get-LastImageTime.ps1
index 5546aaa..6cb4cc5 100644
--- a/FogApi/Public/Get-LastImageTime.ps1
+++ b/FogApi/Public/Get-LastImageTime.ps1
@@ -7,7 +7,16 @@ function Get-LastImageTime {
     Searches the imaging log for the hostid and returns the last entries start time and image used in a descriptive string
     
     .PARAMETER serialNumber
-    The serialnumber to search for, if not specified, it will prompt for input with readhost
+    The serialnumber to search for, if not specified, it will prompt for input with readhost if none is given
+
+    .PARAMETER hostId
+    Specify the hostid to get the image history for
+
+    .PARAMETER fogHost
+    specify the fog host object to get the last history for
+
+    .PARAMETER currentHost
+    switch param to get the current host's foghost object and return the last image time
     
     .EXAMPLE
     Get-LastImageTime
@@ -18,7 +27,22 @@ function Get-LastImageTime {
     And return the full object of the host's imaging log
 
     .EXAMPLE
-    Get-LastImageTime 
+    Get-LastImageTime -currentHost
+    
+    Will get the current computer in fog and return the last image log object.
+    Will also output a descriptive string, i.e. if the hostname is test-pc
+    hostname is test-pc, it was last imaged at 2022-08-18 12:19:38 with the image Win-10-21H2
+
+    .EXAMPLE
+    Get-LastImageTime -hostID 1234
+
+    Will get the foghost with the id 1234 and return the last entry in its image log
+
+    .EXAMPLE
+    $log = Get-LastImageTime -fogHost $hostObj;
+
+    Will put the last image history log for the given host in the $log variable.
+    That $log's properties can then be used in other operations
     
     .NOTES
     Implemented as part of a feature request found in the forums here https://forums.fogproject.org/post/146276
@@ -59,9 +83,18 @@ function Get-LastImageTime {
         
         $imageLog = (get-fogobject -type object -coreObject imaginglog).imagingLogs # get the image history log
         $hostLogs = $imageLog | where-object hostid -eq $HostID # get the image history logs for the given host
-        $hostLog = $hostLogs[-1] # select the last/most recent log
-        #return a string of the information about the serial number
-        "Serial number $serialNumber belongs to host $($fogHost.name), it was last imaged at $($hostLog.start) with the image $($hostLog.image)" | Out-Host
-        return $hostLog;
+        if (!$hostLogs) {
+            Write-Warning "No imaging logs found for host $($fogHost.name)!"
+            return $null;
+        } else {
+            $hostLog = $hostLogs[-1] # select the last/most recent log
+            #return a string of the information about the serial number
+            if ($serialNumber) {
+                "Serial number $serialNumber belongs to host $($fogHost.name), it was last imaged at $($hostLog.start) with the image $($hostLog.image)" | Out-Host
+            } else {
+                "hostname is $($fogHost.name), it was last imaged at $($hostLog.start) with the image $($hostLog.image)" | Out-Host
+            }
+            return $hostLog;
+        } 
     }
 }
\ No newline at end of file