Auto push at 2024-04-27 15:32:46

primoburner · Apr 27, 2024 · e3d7a32 · e3d7a32
1 parent c04922c
commit e3d7a32
Show file tree

Hide file tree

Showing 30 changed files with 500 additions and 138 deletions.
diff --git a/_sources/primoburner-for-cpp/c-utility-classes-and-functions.md b/_sources/primoburner-for-cpp/c-utility-classes-and-functions.md
@@ -12,15 +12,38 @@ This topic lists the utility classes and functions used by the C++ code snippets
 
 ## Functions
 
+### media_state_string
+
+```cpp
+#include <primo/burner/pb.h>
+#include <primo/platform/ustring.h>
+#include <primo/platform/reference++.h>
+
+namespace p = primo;
+namespace pb = primo::burner;
+
+p::ustring media_state_string(pb::MediaReady::Enum media_state)
+{
+    switch (media_state) {
+    case pb::MediaReady::StateUnknown:
+        return "Unknown";
+    case pb::MediaReady::NotPresent:
+        return "Not Present";
+    case pb::MediaReady::Present:
+        return "Present";
+    default:
+        return "Unknown";
+    }
+}
+```
+
 ### media_is_fully_formatted
 
 ``` cpp
 #include <primo/burner/pb.h>
 #include <primo/platform/ustring.h>
 #include <primo/platform/reference++.h>
 
-#include <iostream>
-
 namespace p = primo;
 namespace pb = primo::burner;
 
@@ -50,6 +73,13 @@ const bool media_is_fully_formatted(pb::Device* device)
 ### media_profile_string
 
 ```cpp
+#include <primo/burner/pb.h>
+#include <primo/platform/ustring.h>
+#include <primo/platform/reference++.h>
+
+namespace p = primo;
+namespace pb = primo::burner;
+
 p::ustring media_profile_string(pb::Device* device, pb::MediaProfile::Enum media_profile) {
     switch(media_profile) {
         case pb::MediaProfile::CDRom:
@@ -143,4 +173,3 @@ p::ustring media_profile_string(pb::Device* device, pb::MediaProfile::Enum media
     }
 }
 ```
-
diff --git a/_sources/primoburner-for-cpp/using-device/detect-media-state.md b/_sources/primoburner-for-cpp/using-device/detect-media-state.md
@@ -8,84 +8,156 @@ metadata:
 
 Detect whether there is media in a device or not. This is how you do it:
 
-``` csharp
-private static void DetectMediaPresence(Device device)
+``` cpp
+void detect_media_presense(pb::Device* device)
 {
-    Console.WriteLine("({0}:) - {1}", device.DriveLetter, device.Description);
+    using namespace std;
 
-    Console.WriteLine(" Media State : {0}", device.MediaState);
-    Console.WriteLine(" Unit Ready  : {0}", (DeviceError)device.UnitReady);
+    // get device description
+    auto description = p::ustring(device->description());
 
-    Console.WriteLine(); Console.WriteLine();
+    // get media state and unit ready state (aka device status)
+    auto media_state = device->mediaState();
+    uint32_t unit_ready = device->unitReadyState();
+
+    auto media_state_str = media_state_string(media_state);
+
+    cout << format(" ( {}:) - {}", device->driveLetter(), description.str()) << endl;
+    cout << format("  Media State      : {}", media_state_str.str()) << endl;
+    cout << format("  Unit Ready State : {:#08x}", unit_ready) << endl;
+
+    // get detailed SCSI sense description
+    if (unit_ready != 0) {
+        ScsiInterface *scsi = device->createScsiInterface();
+
+        // derive SCSI sense from unit ready state    
+        ScsiCommandSense sense = {0};
+        sense.Key = (unit_ready >> 16) & 0xFF; // second byte
+        sense.ASC = (unit_ready >> 8) & 0xFF; // third byte
+        sense.ASCQ = unit_ready & 0xFF; // fourth byte
+
+        // get sense message
+        auto sense_message = p::ustring(scsi->getSenseMessage(&sense));
+        
+        cout << format("  SCSI Sense -> Key: {:#04x} ASC: {:#04x} ASCQ: {:#04x} - {}", 
+                       sense.Key, sense.ASC, sense.ASCQ, sense_message.str()) << endl;
+
+        scsi->release();
+    }
+
+    cout << endl;
 }
 ```
 
-## Complete .NET code
+For the `media_state_string` function definition see [C++ Utility Classes and Functions](/primoburner-for-cpp/c-utility-classes-and-functions)
 
-``` csharp
-using System;
-
-using PrimoSoftware.Burner;
 
-namespace DetectMediaPresence
-{
-    class Program
-    {
-        private static void DetectMediaPresence(Device device)
-        {
-            Console.WriteLine("({0}:) - {1}", device.DriveLetter, device.Description);
+## Complete C++ code
 
-            Console.WriteLine(" Media State : {0}", device.MediaState);
-            Console.WriteLine(" Unit Ready  : {0}", (DeviceError)device.UnitReady);
+``` cpp
+#include <primo/burner/pb.h>
+#include <primo/platform/ustring.h>
+#include <primo/platform/reference++.h>
 
-            Console.WriteLine(); Console.WriteLine();
-        }
+#include <iostream>
+#include <format>
 
-        private static void DetectMediaPresence(Engine engine)
-        {
-            // create device enumerator
-            using (var enumerator = engine.CreateDeviceEnumerator())
-            {
-                for (int i = 0; i < enumerator.Count; i++)
-                {
-                    // create a device; do not ask for exclusive access
-                    var device = enumerator.CreateDevice(i, false);
-                    if (null != device)
-                    {
-                        DetectMediaPresence(device);
-                    }
-                }
-            }
-        }
+namespace p = primo;
+namespace pb = primo::burner;
 
-        private static void DetectMediaPresence()
-        {
-            // Create engine
-            using (var engine = new Engine())
-            {
-                // Initialize the engine
-                engine.Initialize();
+p::ustring media_state_string(pb::MediaReady::Enum media_state)
+{
+    switch (media_state) {
+    case pb::MediaReady::StateUnknown:
+        return "Unknown";
+    case pb::MediaReady::NotPresent:
+        return "Not Present";
+    case pb::MediaReady::Present:
+        return "Present";
+    default:
+        return "Unknown";
+    }
+}
 
-                DetectMediaPresence(engine);
+void detect_media_presense(pb::Device* device)
+{
+    using namespace std;
 
-                // terminate engine
-                engine.Shutdown();
-            }
-        }
+    // get device description
+    auto description = p::ustring(device->description());
 
-        static void Main(string[] args)
-        {
-            // Initialize PrimoBurner
-            Library.Initialize();
+    // get media state and unit ready state (aka device status)
+    auto media_state = device->mediaState();
+    uint32_t unit_ready = device->unitReadyState();
 
-            // Set license. To run PrimoBurner in demo mode, comment the next line out
-            Library.SetLicense("license-xml-string");
+    auto media_state_str = media_state_string(media_state);
 
-            // presence 
-            DetectMediaPresence(); 
+    cout << format(" ( {}:) - {}", device->driveLetter(), description.str()) << endl;
+    cout << format("  Media State      : {}", media_state_str.str()) << endl;
+    cout << format("  Unit Ready State : {:#08x}", unit_ready) << endl;
+    
+    // get detailed SCSI sense description
+    if (unit_ready != 0) {
+        ScsiInterface *scsi = device->createScsiInterface();
+
+        // derive SCSI sense from unit ready state    
+        ScsiCommandSense sense = {0};
+        sense.Key = (unit_ready >> 16) & 0xFF; // second byte
+        sense.ASC = (unit_ready >> 8) & 0xFF; // third byte
+        sense.ASCQ = unit_ready & 0xFF; // fourth byte
+
+        // get sense message
+        auto sense_message = p::ustring(scsi->getSenseMessage(&sense));
+        
+        cout << format("  SCSI Sense -> Key: {:#04x} ASC: {:#04x} ASCQ: {:#04x} - {}", 
+                       sense.Key, sense.ASC, sense.ASCQ, sense_message.str()) << endl;
+
+        scsi->release();
+    }
+    
+    cout << endl;
+}
 
-            Library.Shutdown();
+void detect_media_presense(pb::Engine* engine)
+{
+    // create device enumerator
+    auto enumerator = p::make_ref(engine->createDeviceEnumerator());
+
+    for (int i = 0; i < enumerator->count(); i++) {
+        // create a device; do not ask for exclusive access
+        auto device = p::make_ref(enumerator->createDevice(i, false));
+        
+        if (device) {
+            detect_media_presense(device.get());
         }
     }
 }
+
+void detect_media_presense()
+{
+    // Create engine
+    auto engine = p::make_ref(pb::Library::createEngine());
+
+    // Initialize engine
+    engine->initialize();
+
+    detect_media_presense(engine.get());
+
+    // terminate engine
+    engine->shutdown();
+}
+
+int main()
+{
+    // Set license. To run PrimoBurner in demo mode, comment the next line out
+    pb::Library::setLicense("license-xml-string");
+    
+    pb::Library::enableTraceLog();
+    
+    detect_media_presense();
+    
+    pb::Library::disableTraceLog();
+
+    return 0;
+}
 ```
diff --git a/about-primoburner/about-primoburner-for-c/index.html b/about-primoburner/about-primoburner-for-c/index.html
@@ -241,6 +241,11 @@ <h1 class="site-logo" id="site-title">PrimoBurner for C++</h1>
    </i>
   </label>
   <ul>
+   <li class="toctree-l2">
+    <a class="reference internal" href="../../primoburner-for-cpp/using-device/detect-media-state/">
+     Detect Media Presence
+    </a>
+   </li>
    <li class="toctree-l2">
     <a class="reference internal" href="../../primoburner-for-cpp/using-device/read-media-info/">
      Read Media Info

diff --git a/about-primoburner/demo-version/index.html b/about-primoburner/demo-version/index.html
@@ -241,6 +241,11 @@ <h1 class="site-logo" id="site-title">PrimoBurner for C++</h1>
    </i>
   </label>
   <ul>
+   <li class="toctree-l2">
+    <a class="reference internal" href="../../primoburner-for-cpp/using-device/detect-media-state/">
+     Detect Media Presence
+    </a>
+   </li>
    <li class="toctree-l2">
     <a class="reference internal" href="../../primoburner-for-cpp/using-device/read-media-info/">
      Read Media Info

diff --git a/api-docs/index.html b/api-docs/index.html
@@ -241,6 +241,11 @@ <h1 class="site-logo" id="site-title">PrimoBurner for C++</h1>
    </i>
   </label>
   <ul>
+   <li class="toctree-l2">
+    <a class="reference internal" href="../primoburner-for-cpp/using-device/detect-media-state/">
+     Detect Media Presence
+    </a>
+   </li>
    <li class="toctree-l2">
     <a class="reference internal" href="../primoburner-for-cpp/using-device/read-media-info/">
      Read Media Info

diff --git a/genindex/index.html b/genindex/index.html
@@ -238,6 +238,11 @@ <h1 class="site-logo" id="site-title">PrimoBurner for C++</h1>
    </i>
   </label>
   <ul>
+   <li class="toctree-l2">
+    <a class="reference internal" href="../primoburner-for-cpp/using-device/detect-media-state/">
+     Detect Media Presence
+    </a>
+   </li>
    <li class="toctree-l2">
     <a class="reference internal" href="../primoburner-for-cpp/using-device/read-media-info/">
      Read Media Info

diff --git a/index.html b/index.html
@@ -240,6 +240,11 @@ <h1 class="site-logo" id="site-title">PrimoBurner for C++</h1>
    </i>
   </label>
   <ul>
+   <li class="toctree-l2">
+    <a class="reference internal" href="primoburner-for-cpp/using-device/detect-media-state/">
+     Detect Media Presence
+    </a>
+   </li>
    <li class="toctree-l2">
     <a class="reference internal" href="primoburner-for-cpp/using-device/read-media-info/">
      Read Media Info