﻿/*
 * Copyright (c) Omnissa, LLC. All rights reserved.
 * This product is protected by copyright and intellectual property laws in the
 * United States and other countries as well as by international treaties.
 * -- Omnissa Restricted
 */

========================================================================
    VDPService - Horizon Session Enhancement SDK
========================================================================


Introduction
-----------------------------------------------------------------------
VDPService is a set of interfaces that can be used by applications
running on a Horizon remote desktop to extend the feature set of
Horizon.  There are two main interfaces:

    RPC - a communication library which provides a messaging capability
    between an application running on the Horizon remote desktop and
    a plugin running in the Horizon Client.

    Overlay - a simple graphics library that can be used to render
    images from your Horizon Client plugin such that they appear to
    be in a window on the Horizon remote desktop.  It can be used
    as the foundation of media redirection.

    ScreenCapture - an interface allows for copying the image of the
    entire screen of the remote desktop or of a single application
    window on the remote desktop.


NOTE: Within this document, file paths, registry keys, and similar code
related items are revised to reflect the SDK's use with the Omnissa stack
References to items that were for Horizon versions 8.13/2406 and earlier
contain asterisks (V**** or V**) to redact the previous name.


SDK files
-----------------------------------------------------------------------
   include\                      - A folder with the C header files
   include\vdpService_import.cpp - C++ source for an import library
   samples\pingrpc               - RPC sample application
   samples\overlay\LocalOverlay  - Local overlay sample application
   samples\overlay\VMR9Overlay   - Video redirection sample application

   Previous versions of the SDK included vdpService.dll.  This DLL is
   no longer included as part of the SDK because it is included with
   Horizon, and has been since 2009.  Your application must use the
   version of vdpService.dll that ships with Horizon.  Using a different
   version of vdpService.dll may cause problems with previous and future
   versions of Horizon because this DLL is matched with other DLLs that
   ship with Horizon.  The import library, vdpService_import.cpp, knows
   how to find and load the correct version of vdpService.dll.  Include
   this source file in your project to load the dll and get the API
   function entry points.


Collecting VDPService Logs
--------------------------------------------------------------------

1) On the remote desktop side, for every application that loads
   vdpService.dll a separate log file will be created -
   horizon-vdpService-<APP_NAME>-<sid>-<pid>__<date-time>.log

2) On the client side, vdpService.dll creates a single log file
   that is shared by all the plugins that are loaded -
   horizon-vdpService-Client-<sid>-<pid>__<date-time>.log

3) There are a number of configuration settings for vdpService logs.  Here are a few:

  a) logLevel - controls the amount of information written to the log file.  There
     are 5 levels - TRACE, DEBUG, INFO, WARN and ERROR.  The default is INFO.
     Logging is expensive, do not run performance tests with increased log levels.

  b) logMaxDaysKept - controls how long old log files are kept.  Only log files
     generated by your application will be deleted; i.e. log files generated by
     application A will only be automatically deleted when application A is running.
     The default is 7.  Set the value to 0 is disable this feature.

  c) logMaxRollingFiles - controls the number of log files to keep for the current
     process.  If the process is long lived, and the log file grows too big, a new
     log file is started and a counter is added to the name of the log file.  This
     values controls how many of the log files are kept.  The first log file has
     important startup information and is always kept.  The default is 5.  Set the
     value to 0 to disable this feature and keep all log files.

     For example, when the log file rolls from
     horizon-vdpService-myApp-1-1234(6)__<date-time>.log to
     horizon-vdpService-myApp-1-1234(7)__<date-time>.log then
     horizon-vdpService-myApp-1-1234(2)__<date-time>.log would be deleted.

  d) logDiskThresholdLowMB
     logDiskThresholdHighMB - controls when logging is suspended due to low disk
     space.  Should the amount of free disk space drop below the low threshold
     logging will be suspended and will not resume until the amount of free disk
     space is above the high threshold.  While suspended the logger will discard
     messages.  Default values are logDiskThresholdLowMB:200 and
     logDiskThresholdHighMB:500.

4) Starting with Horizon Agent v7.7 and Horizon Client v4.10 changes to
   the log settings are updated without having to restart the application.
   Previous to that the log settings are only read when the application starts.

5) Windows
  a) Configuration settings are read from the registry.
         [HKEY_LOCAL_MACHINE\SOFTWARE\Omnissa\Horizon\VDPService]
         "logLevel"="TRACE"

        Horizon 8.13 and earlier uses the legacy locations
            [HKEY_LOCAL_MACHINE\SOFTWARE\V*****, Inc.\V***** VDPService]
            "logLevel"="TRACE"

  b) Client side logs can be found here:
         C:\Users\<USER_NAME>\AppData\Local\Temp\omnissa-<USER_NAME>

        Horizon 8.13 and earlier uses the legacy locations
            C:\Users\<USER_NAME>\AppData\Local\Temp\v*****-<USER_NAME>

  c) Server side logs for user processes can be found here:
         C:\Users\<USER_NAME>\AppData\Local\Temp\omnissa-<USER_NAME>

        Horizon 8.13 and earlier uses the legacy locations
            C:\Users\<USER_NAME>\AppData\Local\Temp\v*****-<USER_NAME>

  d) Server side logs for system processes can be found here:
         C:\ProgramData\Omnissa\Horizon\logs

        Horizon 8.13 and earlier uses the legacy locations
            C:\ProgramData\V*****\VDM\logs

6) Linux
  a) Configuration settings are set via a file
         ~/.omnissa/config
         vdpService.log.logLevel=trace

        Horizon 8.13 and earlier uses the legacy locations
            ~/.v*****/config
            vdpService.log.logLevel=trace

  b) Logs can be found here:
         /tmp/omnissa-<USER-NAME>

        Horizon 8.13 and earlier uses the legacy locations
            /tmp/v*****-<USER-NAME>


7) Mac
  a) Configuration settings are set via a file
         /Users/<USER-NAME>/Library/Preferences/Omnissa Horizon Client/config
         vdpService.log.logLevel=trace

        Horizon 8.13 and earlier uses the legacy locations
            /Users/<USER-NAME>/Library/Preferences/V***** Horizon Client/config
            vdpService.log.logLevel=trace

  b) Logs can be found here:
         /Users/<USER-NAME>/Library/Logs/Omnissa

        Horizon 8.13 and earlier uses the legacy locations
            /Users/<USER-NAME>/Library/Logs/V*****


Publicly Released Versions
-----------------------------------------------------------------------
URL of Public Release:
  https://developer.omnissa.com/horizon-sdks/view-session-management/

* Version 1.0.0:
- Released in Nov 2013
- Build: 1404318
- VDI Agent support & Client support for Windows, Linux & Mac

* Version 2.0.0:
- Released in Dec 2014
- Build: 2351061
- Overlay - Clip region support added
- Overlay - Layer support added
- Bug Fixes

* Version 3.0.0:
- Released in March 2016
- Build: 3644347
- Blast/VVC support added
- Windows RDSH support added
- RPC - Encryption support added
- RPC - Compression support added
- RPC - Observer interface implemented
- RPC - StreamData interface implemented
- Overlay - DirectX shared surfaces support added
- Bug Fixes

* Version 3.1.0:
- Released in Dec 2016
- Build: 4686475
- RPC - Low priviledge support added
- Overlay - YV12 surface support added
- Bug Fixes

* Version 3.2.0:
- Released in Sep 2017
- Build: 6570438
- RPC - VVC/BEAT side channel support added
- Bug Fixes

* Version 3.3.0:
- Build: 18347885 (Jul 19, 2021)
- All binaries have been removed from the SDK
- Import library, vdpService_import.cpp, was added
- RPC - MultiServer support added (experimental)
- Overlay - TILE LayoutMode implemented
- Overlay - MULTIPLE LayoutMode implemented
- Overlay - AreaRect support added
- Overlay - Background color support added
- Overlay - InfoStr/text support added
- Overlay - Remote desktop topology support added
- Bug Fixes

* Version 4.0.0:
- Build: 14304348675 (Apr 07, 2025)
- First Omnissa release of SDK.  Prior versions 1.0.0 to 3.3.0 are no longer available.
- ScreenCapture - New interface introduced to assist with capturing the contents of the Horizon client window.
- ReadBackWindow - Functions included with the ScreenCapture interface to allow for reading the contents of
  a specific window on the remote desktop.
- Overlay - YUVI420 format added to support ScreenCapture and ReadBackWindow interfaces.
- Sample Makefiles updated to build on Mac
- Bug Fixes

* Version 4.1.0:
- Build: 33647416260 (Sep 02, 2026)
- ScreenCapture.v5 implemented - GetHostWindowForDesktop
- ScreenCapture.v7 implemented - GetHostWindowsForDesktop (per-monitor macOS host
  window identifiers (CGWindowID) and backing scale)
