C# Bindings
===========

The C# content in ``examples/language_bindings/csharp`` is a reference
integration over the CosmicSDK C API. It demonstrates one clean way to
integrate from C#, but it is not an official C# SDK package.

Example Layout
--------------

The C# examples mirror the native C/C++ blocking examples:

.. code-block:: text

   examples/language_bindings/csharp/
   |- src/CosmicDriver/
   |- examples/system/
   |- examples/i2c/
   |- examples/spi/
   |- examples/uart/
   |- examples/gpio/
   |- examples/i3c/basic/
   |- examples/i3c/daa/
   |- examples/i3c/ccc/
   |- examples/i3c/hdr-ddr/
   |- examples/i3c/hj-ibi/
   |- CosmicSdkCSharpExamples.sln

Windows
-------

1. **Navigate to the C# binding directory**

.. code-block:: powershell

   cd /path/to/CosmicSDK/examples/language_bindings/csharp

2. **Set `COSMICSDK_LIB_PATH`**

Point it either to the directory containing the shared library, or to the
full path of the library itself.

- Command Prompt

.. code-block:: bat

   set COSMICSDK_LIB_PATH=<path-to-CosmicSDK-library-or-lib-folder>

- PowerShell

.. code-block:: powershell

   $env:COSMICSDK_LIB_PATH="<path-to-CosmicSDK-library-or-lib-folder>"

3. **Build all C# binding projects**

.. code-block:: powershell

   dotnet build CosmicSdkCSharpExamples.sln

4. **Run one example**

.. code-block:: powershell

   dotnet run --project .\examples\system\system.csproj
   dotnet run --project .\examples\i2c\i2c.csproj
   dotnet run --project .\examples\i3c\basic\basic.csproj

macOS
-----

1. **Navigate to the C# binding directory**

.. code-block:: bash

   cd /path/to/CosmicSDK/examples/language_bindings/csharp

2. **Set `COSMICSDK_LIB_PATH` and run one example**

.. code-block:: bash

   export COSMICSDK_LIB_PATH=/path/to/cosmicsdk/lib
   dotnet run --project ./examples/i2c/i2c.csproj

If loading fails because of missing transitive ``.dylib`` dependencies, set:

.. code-block:: bash

   export DYLD_LIBRARY_PATH=$COSMICSDK_LIB_PATH:$DYLD_LIBRARY_PATH

Linux
-----

1. **Navigate to the C# binding directory**

.. code-block:: bash

   cd /path/to/CosmicSDK/examples/language_bindings/csharp

2. **Set `COSMICSDK_LIB_PATH` and `LD_LIBRARY_PATH`, then run one example**

.. code-block:: bash

   export COSMICSDK_LIB_PATH=/path/to/cosmicsdk/lib
   export LD_LIBRARY_PATH=$COSMICSDK_LIB_PATH:$LD_LIBRARY_PATH
   dotnet run --project ./examples/i2c/i2c.csproj

Notes
-----

- The ``CosmicDriver`` project is intentionally a thin C-interop layer using
  P/Invoke, designed for readability and adaptation.
- Notification-driven examples (for example ``i3c/hj-ibi``) use the C
  notification callback API and parse payloads through the provided helpers.
- On Linux, ``LD_LIBRARY_PATH`` may be required so the runtime can resolve
  transitive native dependencies (for example ``libhidapi-libusb.so.0``).
- On macOS, if dependency resolution fails, use ``DYLD_LIBRARY_PATH``.
- This code is maintained as integration reference material and should be
  treated as a starting point for custom C# solutions.