ntv2nubaccess.h

Go to the documentation of this file.

/* SPDX-License-Identifier: MIT */
#ifndef NTV2NUBACCESS_H
#define NTV2NUBACCESS_H

#include "ntv2utils.h"                  //  NTV2StringList
#include "ajabase/system/lock.h"        //  AJALock
#include <string>
#include <vector>
#include <map>

//  TYPEDEFs
typedef std::pair<NTV2DeviceID, ULWord64>       NTV2DeviceIDSerialPair;     
typedef std::vector<NTV2DeviceIDSerialPair>     NTV2DeviceIDSerialPairs;    
typedef NTV2DeviceIDSerialPairs::iterator       NTV2DeviceIDSerialPairsIter;
typedef NTV2DeviceIDSerialPairs::const_iterator NTV2DeviceIDSerialPairsConstIter;

//  Supported NTV2ConnectParams:
#define kConnectParamScheme     "scheme"        
#define kConnectParamHost       "host"          
#define kConnectParamPort       "port"          
#define kConnectParamDevIndex   "deviceindex"   
#define kConnectParamDevSerial  "deviceserial"  
#define kConnectParamDevModel   "devicemodel"   
#define kConnectParamDevID      "deviceid"      
#define kConnectParamResource   "resourcePath"  
#define kConnectParamQuery      "query"         

//  AJA query params:
#define kQParamVerboseLogging   "verbose"       
#define kQParamLogToStdout      "stdout"        
#define kQParamShowX509Cert     "showcert"      
#define kQParamShowParams       "showparams"    
#define kQParamDebugRegistry    "debugregistry" 
#define kQParamNumWorkers       "numworkers"    

//  AJA VDEV params:
#define kQParamVDevFolderPath   "vdevfpath"     
#define kQParamVDevName         "vdevname"      
#define kQParamVDevFileName     "vdevfname"     
#define kQParamVDevIndex        "vdevindex"     

//  AJA VDEV JSON keys:
#define kVDevJSON_Name          "name"          
#define kVDevJSON_URLSpec       "urlspec"       
#define kVDevJSON_Disabled      "disabled"      
#define kVDevJSON_Plugin        "plugin"        
#define kVDevJSON_Host          "host"          

//  Local URL schemes:
#define kLegalSchemeNTV2        "ntv2"
#define kLegalSchemeNTV2Local   "ntv2local"

//  Exported Function Names:
#define kFuncNameCreateClient   "CreateClient"          
#define kFuncNameCreateServer   "CreateServer"          
#define kFuncNameGetRegInfo     "GetRegistrationInfo"   

//  Other Info Keys:
#define kNTV2PluginInfoKey_PluginsPath          "PluginsPath"       
#define kNTV2PluginInfoKey_PluginPath           "PluginPath"        
#define kNTV2PluginInfoKey_PluginSigPath        "PluginSigPath"     
#define kNTV2PluginInfoKey_PluginBaseName       "PluginBaseName"    
#define kNTV2PluginInfoKey_Fingerprint          "serial number"     
#define kNTV2PluginInfoKey_Errors               "errors"            

//  Plugin Registration Info Keys:
#define kNTV2PluginRegInfoKey_Vendor            "Vendor"            
#define kNTV2PluginRegInfoKey_CommonName        "CommonName"        
#define kNTV2PluginRegInfoKey_OrgUnit           "OrgUnit"           
#define kNTV2PluginRegInfoKey_ShortName         "ShortName"         
#define kNTV2PluginRegInfoKey_LongName          "LongName"          
#define kNTV2PluginRegInfoKey_Description       "Description"       
#define kNTV2PluginRegInfoKey_Copyright         "Copyright"         
#define kNTV2PluginRegInfoKey_NTV2SDKVersion    "NTV2SDKVersion"    
#define kNTV2PluginRegInfoKey_Version           "Version"           
#define kNTV2PluginRegInfoKey_CommitSHA         "CommitSHA"         
#define kNTV2PluginRegInfoKey_ReqParams         "RequiredParams"    
#define kNTV2PluginRegInfoKey_OptParams         "OptionalParams"    

//  Plugin Signature File Keys:
#define kNTV2PluginSigFileKey_X509Certificate   "X509Certificate"   
#define kNTV2PluginSigFileKey_Signature         "Signature"         

//  X509 Certificate Attribute Keys:
#define kNTV2PluginX500AttrKey_CommonName               "CN"
#define kNTV2PluginX500AttrKey_LocalityName             "L"
#define kNTV2PluginX500AttrKey_StateOrProvinceName      "ST"
#define kNTV2PluginX500AttrKey_OrganizationName         "O"
#define kNTV2PluginX500AttrKey_OrganizationalUnitName   "OU"
#define kNTV2PluginX500AttrKey_CountryName              "C"

extern uint32_t gBaseConstructCount;    //  Number of NTV2RPCBase constructor calls made
extern uint32_t gBaseDestructCount;     //  Number of NTV2RPCBase destructor calls made
extern uint32_t gClientConstructCount;  //  Number of NTV2RPCClient constructor calls made
extern uint32_t gClientDestructCount;   //  Number of NTV2RPCClient destructor calls made
extern uint32_t gServerConstructCount;  //  Number of NTV2RPCServer constructor calls made
extern uint32_t gServerDestructCount;   //  Number of NTV2RPCServer destructor calls made
extern uint32_t gLoaderConstructCount;  //  Number of NTV2PluginLoader constructor calls made
extern uint32_t gLoaderDestructCount;   //  Number of NTV2PluginLoader destructor calls made
extern uint32_t gPluginConstructCount;  //  Number of NTV2Plugin constructor calls made
extern uint32_t gPluginDestructCount;   //  Number of NTV2Plugin destructor calls made

class AJAExport NTV2Dictionary
{
    public:
        inline size_t       size (void) const   {return mDict.size();}  
        inline bool         empty (void) const  {return mDict.empty();} 
        inline bool         hasKey (const std::string & inKey) const    {return mDict.find(inKey) != mDict.end();}  
        std::string         valueForKey (const std::string & inKey) const;  
        uint16_t            u16ValueForKey (const std::string & inKey, const uint16_t inDefault = 0) const; 
        NTV2StringSet       keys (void) const;  
        size_t              largestKeySize (void) const;    
        size_t              largestValueSize (void) const;  
        std::ostream &      Print (std::ostream & oss, const bool inCompact = true) const;  
        bool                serialize (std::string & outStr) const; 

        inline void         clear (void)    {mDict.clear();}        
        bool                insert (const std::string & inKey, const std::string & inValue);    
        inline size_t       erase (const std::string & inKey)   {return hasKey(inKey) ? mDict.erase(inKey) : 0;}    
        size_t              updateFrom (const NTV2Dictionary & inDict); 
        size_t              addFrom (const NTV2Dictionary & inDict);    
        bool                deserialize (const std::string & inStr);    
    #if !defined(NTV2_DEPRECATE_17_1)
        inline NTV2_DEPRECATED_f(size_t UpdateFrom (const NTV2Dictionary & inDict)) {return updateFrom(inDict);}    
        inline NTV2_DEPRECATED_f(size_t AddFrom (const NTV2Dictionary & inDict)) {return addFrom(inDict);}  
    #endif  //  !defined(NTV2_DEPRECATE_17_1)

    public:
        typedef std::map<std::string, std::string>  Dict;
        typedef Dict::const_iterator                DictConstIter;
        inline size_t       initializeFrom (const Dict & inDict)    {mDict = inDict; return size();}

    private:
        Dict    mDict;  
};  //  NTV2Dictionary

typedef NTV2Dictionary  NTV2Dict;
typedef NTV2Dictionary  NTV2ConnectParams;      
typedef NTV2Dictionary  NTV2ConfigParams;       
typedef std::pair<std::string, std::string>     NTV2DictionaryEntry, NTV2DictEntry, NTV2ConnectParam;   

inline std::ostream & operator << (std::ostream & oss, const NTV2Dictionary & inDict)   {return inDict.Print(oss);}

class AJAExport NTV2DeviceSpecParser
{
    public:
                                        NTV2DeviceSpecParser (const std::string inSpec = "");   
        void                            Reset (const std::string inSpec = "");  
        inline const std::string &      DeviceSpec (void) const                     {return mSpec;}     
        std::string                     MakeDeviceSpec (const bool urlEncodeQuery) const;   
        std::string                     MakeQueryString (const bool urlEncode) const;       
        inline bool                     HasDeviceSpec (void) const                  {return !DeviceSpec().empty();} 
        inline bool                     Successful (void) const                     {return !Failed();} 
        inline bool                     Failed (void) const                         {return DeviceSpec().empty() ? true : HasErrors();} 
        inline bool                     HasScheme (void) const                      {return HasResult(kConnectParamScheme);}    
        inline std::string              Scheme (void) const                         {return Result(kConnectParamScheme);}   
        inline bool                     IsLocalDevice (void) const                  {return Scheme() == kLegalSchemeNTV2Local || Scheme() == kLegalSchemeNTV2;} 
        inline size_t                   ErrorCount (void) const                     {return mErrors.size();}    
        inline bool                     HasErrors (void) const                      {return ErrorCount() > 0;}  
        inline std::string              Error (const size_t inIndex = 0) const      {if (inIndex < mErrors.size()) return mErrors.at(inIndex); return "";}  
        inline NTV2StringList           Errors (void) const                         {return mErrors;}   
        inline NTV2ConnectParams        Results (void) const                        {return mResult;}   
        inline bool                     HasResult (const std::string & inKey) const {return mResult.hasKey(inKey);} 
        std::string                     Result (const std::string & inKey) const    {return mResult.valueForKey(inKey);}    
        std::string                     Resource (const bool inStripLeadSlash = true) const;    
        std::ostream &                  PrintErrors (std::ostream & oss) const;
        std::ostream &                  Print (std::ostream & oss, const bool inDumpResults = false) const;
        std::string                     InfoString (void) const;
        std::string                     DeviceSerial (void) const                   {return Result(kConnectParamDevSerial);}
        inline std::string              DeviceModel (void) const                    {return Result(kConnectParamDevModel);}
        NTV2DeviceID                    DeviceID (void) const;
        UWord                           DeviceIndex (void) const;
        inline const NTV2Dictionary &   QueryParams (void) const                    {return mQueryParams;}  
        inline std::string              QueryParam (const std::string & inKey) const    {return mQueryParams.valueForKey(inKey);}   
        inline bool                     HasQueryParams (void) const                 {return !QueryParams().empty();}    
        #if defined(_DEBUG)
        static void                     test (void);
        #endif  //  defined(_DEBUG)

    private:
        void            Parse (void);
        bool            ParseHexNumber (size_t & pos, std::string & outToken);
        bool            ParseDecNumber (size_t & pos, std::string & outToken);
        bool            ParseAlphaNum (size_t & pos, std::string & outToken, const std::string & inOtherChars = "");    //  Starts with letter followed by run of letters and/or digits and/or other chars
        bool            ParseAlphaNumeric (size_t & pos, std::string & outToken, const std::string & inOtherChars = "");    //  A run of letters and/or decimal digits and/or other chars
        bool            ParseScheme (size_t & pos, std::string & outToken); //  An alphanumeric name followed by "://"
        bool            ParseSerialNum (size_t & pos, std::string & outToken);  //  An 8 or 9 character alphanumeric name or a 64-bit hex number
        bool            ParseDeviceID (size_t & pos, std::string & outToken);   //  An 32-bit hex number that matches a known NTV2DeviceID
        bool            ParseModelName (size_t & pos, std::string & outToken);  //  An alphanumeric name that matches a known device model name
        bool            ParseDNSName (size_t & pos, std::string & outDNSName);  //  A domain name:  one or more alphanumeric names separated with '.'
        bool            ParseIPv4Address (size_t & pos, std::string & outIPv4); //  Exactly four decimal numbers, each no greater than 255, separated with '.'
        bool            ParseHostAddressAndPortNumber (size_t & pos, std::string & outAddr, std::string & outPort); //  A host name or IPv4 address with an optional port number
        bool            ParseResourcePath (size_t & pos, std::string & outRsrc);    //  One or more '/'-separated alphanumeric names
        bool            ParseParamAssignment (size_t & pos, std::string & outKey, std::string & outValue);  //  An alphanumeric key optionally followed by '=' optionally followed by URL-encoded value string
        bool            ParseQuery (size_t & pos, NTV2Dictionary & outParams);  //  Starts with '?' one or more '&'-separated param assignments
        inline int      LargestResultKey (void) const               {return int(mResult.largestKeySize());}
        inline int      LargestResultValue (void) const             {return int(mResult.largestValueSize());}
        inline char     CharAt (const size_t inPos)                 {return inPos < mSpec.length() ? mSpec.at(inPos) : 0;}
        inline size_t   SpecLength (void) const                     {return mSpec.length();}
        inline size_t   CurrentPosition (void) const                {return mPos;}
        inline void     AddError (const std::string & inError)      {mErrors.push_back(inError);}
        static bool     IsUpperLetter (const char inChar);
        static bool     IsLowerLetter (const char inChar);
        static bool     IsLetter (const char inChar, const bool inIncludeUnderscore = false);
        static bool     IsDecimalDigit (const char inChar);
        static bool     IsHexDigit (const char inChar);
        static bool     IsLegalSerialNumChar (const char inChar);

    private:
        std::string         mSpec;          
        NTV2StringList      mErrors;        
        NTV2ConnectParams   mResult;        
        NTV2Dictionary      mQueryParams;   
        size_t              mPos;           

    public: //  Class Methods
        static bool     ParseQueryParams (const NTV2Dictionary & inSrcDict, NTV2Dictionary & outQueryParams);
};  //  NTV2DeviceSpecParser


class AJAExport NTV2RPCBase
{
    public:
        static std::string ShortSDKVersion (void);  
        static std::string AJAFingerprint (const bool inLowerCase = false, const bool inStripColons = false);   

    protected:
                        NTV2RPCBase (NTV2Dictionary params, uint32_t * pRefCon);
        virtual         ~NTV2RPCBase ();
        bool            SetParams (const NTV2ConfigParams & inNewParams, const bool inAugment = false);

    protected:
        NTV2Dictionary  mParams;        
        mutable AJALock mParamLock;     
        uint32_t *      mpRefCon;       
};  //  NTV2RPCBase


class AJAExport NTV2RPCClientAPI : public NTV2RPCBase
{
    public:
        static NTV2RPCClientAPI *   CreateClient (NTV2ConnectParams & inParams);

    public:
        virtual std::string     HostName (void) const   {return ConnectParam(kConnectParamHost);}   
        virtual std::string     Name (void) const       {return "";}    
        virtual std::string     Description (void) const;   
        virtual std::ostream &  Print (std::ostream & oss) const;

        virtual bool    NTV2Connect (void);
        virtual bool    NTV2Disconnect (void);      
        virtual bool    IsConnected (void) const    {return false;} 

        virtual NTV2ConnectParams   ConnectParams (void) const; 
        virtual bool                HasConnectParam (const std::string & inParam) const;    
        virtual std::string         ConnectParam (const std::string & inParam) const;   
        virtual bool                ConnectHasScheme (void) const;  
        virtual inline bool         SetConnectParams (const NTV2ConnectParams & inNewParams, const bool inAugment = false) {return !IsConnected() && SetParams(inNewParams, inAugment);}    

        virtual bool    NTV2ReadRegisterRemote  (const ULWord regNum, ULWord & outRegValue, const ULWord regMask, const ULWord regShift);
        virtual bool    NTV2WriteRegisterRemote (const ULWord regNum, const ULWord regValue, const ULWord regMask, const ULWord regShift);
        virtual bool    NTV2AutoCirculateRemote (AUTOCIRCULATE_DATA & autoCircData);
        virtual bool    NTV2WaitForInterruptRemote  (const INTERRUPT_ENUMS eInterrupt, const ULWord timeOutMs);
        virtual bool    NTV2DMATransferRemote       (const NTV2DMAEngine inDMAEngine,   const bool inIsRead,
                                                    const ULWord inFrameNumber,         NTV2Buffer & inOutBuffer,
                                                    const ULWord inCardOffsetBytes,     const ULWord inNumSegments,
                                                    const ULWord inSegmentHostPitch,    const ULWord inSegmentCardPitch,
                                                    const bool inSynchronous);
        virtual bool    NTV2MessageRemote   (NTV2_HEADER *  pInMessage);

        virtual bool    NTV2GetBoolParamRemote (const ULWord inParamID,  ULWord & outValue);    //  New in SDK 17.0
        virtual bool    NTV2GetNumericParamRemote (const ULWord inParamID,  ULWord & outValue); //  New in SDK 17.0
        virtual bool    NTV2GetSupportedRemote (const ULWord inEnumsID, ULWordSet & outSupported);  //  New in SDK 17.0

        virtual bool    NTV2QueryDevices (NTV2StringList & outDeviceInfos, std::string & outErrMsg)
        {
            outErrMsg.clear();
            outDeviceInfos.clear();
            return true;
        }

        #if !defined(NTV2_DEPRECATE_16_3)   //  These functions are going away
        virtual NTV2_DEPRECATED_16_3(bool NTV2DriverGetBitFileInformationRemote(BITFILE_INFO_STRUCT & nfo, const NTV2BitFileType typ));
        virtual NTV2_DEPRECATED_16_3(bool NTV2DriverGetBuildInformationRemote(BUILD_INFO_STRUCT & buildInfo));
        virtual NTV2_DEPRECATED_16_3(bool NTV2DownloadTestPatternRemote(const NTV2Channel ch, const NTV2PixelFormat pf, const UWord msk, const bool dma, const ULWord tpNum));
        virtual NTV2_DEPRECATED_16_3(bool NTV2ReadRegisterMultiRemote(const ULWord numRegs, ULWord & outFailedRegNum, NTV2RegInfo outRegs[]));
        virtual NTV2_DEPRECATED_16_3(bool NTV2GetDriverVersionRemote(ULWord & vers));
        #endif  //  !defined(NTV2_DEPRECATE_16_3)

        virtual         ~NTV2RPCClientAPI();    

    protected:
                        NTV2RPCClientAPI (NTV2ConnectParams inParams, void * pRefCon);  

        virtual bool    NTV2OpenRemote  (void);
        virtual bool    NTV2CloseRemote (void);

    protected:
        uint32_t    mSpare[1024];       
};  //  NTV2RPCClientAPI

typedef NTV2RPCClientAPI NTV2RPCAPI;

inline std::ostream & operator << (std::ostream & oss, const NTV2RPCClientAPI & inObj)  {return inObj.Print(oss);}

class AJAExport NTV2RPCServerAPI : public NTV2RPCBase
{
    public:
        static NTV2RPCServerAPI *   CreateServer (NTV2ConfigParams & inParams);

        static NTV2RPCServerAPI *   CreateServer (const std::string & inURL);

    public:
        virtual std::ostream &  Print (std::ostream & oss) const;
        virtual inline bool     IsRunning (void) const  {return mRunning;}  

        virtual NTV2ConfigParams    ConfigParams (void) const;  
        virtual bool                HasConfigParam (const std::string & inParam) const; 
        virtual std::string         ConfigParam (const std::string & inParam) const;    
        virtual inline bool         SetConfigParams (const NTV2ConfigParams & inNewParams, const bool inAugment = false) {return SetParams(inNewParams, inAugment);}    

        virtual void        RunServer   (void); 
        virtual inline void Stop        (void)  {mTerminate = true;}    

    protected:
                            NTV2RPCServerAPI (NTV2ConnectParams inParams, void * pRefCon);  
        virtual             ~NTV2RPCServerAPI();    

    protected:
        bool        mRunning;       
        bool        mTerminate;     
        uint32_t    mSpare[1024];   
};  //  NTV2RPCServerAPI

inline std::ostream & operator << (std::ostream & oss, const NTV2RPCServerAPI & inObj)  {return inObj.Print(oss);}

extern "C"
{
    typedef bool (*fpGetRegistrationInfo) (const uint32_t /*inHostSDKVers*/, NTV2Dictionary & /*outInfo*/);

    typedef NTV2RPCClientAPI* (*fpCreateClient) (void * /*pRefCon*/, const NTV2ConnectParams & /*inParams*/, const uint32_t /*inHostSDKVersion*/);

    typedef NTV2RPCServerAPI* (*fpCreateServer) (void * /*pRefCon*/, const NTV2ConfigParams & /*inParams*/, const uint32_t /*inHostSDKVersion*/);

    #if !defined(NTV2_DEPRECATE_16_3)   //  Don't use these functions going forward
    typedef NTV2RPCAPI* (*fpCreateNTV2SoftwareDevice) (void * /*pInDLLHandle*/, const std::string & /*inQueryStr*/, const uint32_t /*inHostSDKVersion*/);
    #endif  //  !defined(NTV2_DEPRECATE_16_3)
}

#endif  //  NTV2NUBACCESS_H