AJA NTV2 SDK  17.0.1.1246
NTV2 SDK 17.0.1.1246
ntv2nubaccess.h
Go to the documentation of this file.
1 /* SPDX-License-Identifier: MIT */
8 #ifndef NTV2NUBACCESS_H
9 #define NTV2NUBACCESS_H
10 
11 #include "ntv2utils.h" // NTV2StringList
12 #include <string>
13 #include <vector>
14 #include <map>
15 
16 // TYPEDEFs
17 typedef std::pair<NTV2DeviceID, ULWord64> NTV2DeviceIDSerialPair;
18 typedef std::vector<NTV2DeviceIDSerialPair> NTV2DeviceIDSerialPairs;
19 typedef NTV2DeviceIDSerialPairs::iterator NTV2DeviceIDSerialPairsIter;
20 typedef NTV2DeviceIDSerialPairs::const_iterator NTV2DeviceIDSerialPairsConstIter;
21 
22 // Supported NTV2ConnectParams:
23 static const std::string kConnectParamScheme ("Scheme");
24 static const std::string kConnectParamHost ("Host");
25 static const std::string kConnectParamPort ("Port");
26 static const std::string kConnectParamDevIndex ("DeviceIndex");
27 static const std::string kConnectParamDevSerial ("DeviceSerial");
28 static const std::string kConnectParamDevModel ("DeviceModel");
29 static const std::string kConnectParamDevID ("DeviceID");
30 static const std::string kConnectParamResource ("ResourcePath");
31 static const std::string kConnectParamQuery ("Query");
32 
33 // Local URL schemes:
34 static const std::string kLegalSchemeNTV2 ("ntv2");
35 static const std::string kLegalSchemeNTV2Local ("ntv2local");
36 
37 // Exported Function Names:
38 static const std::string kFuncNameCreateClient ("CreateClient");
39 static const std::string kFuncNameCreateServer ("CreateServer");
40 
44 class AJAExport NTV2Dictionary
45 {
46  public:
50  inline size_t size (void) const {return mDict.size();}
52  inline bool empty (void) const {return mDict.empty();}
53  inline bool hasKey (const std::string & inKey) const {return mDict.find(inKey) != mDict.end();}
54  std::string valueForKey (const std::string & inKey) const;
55  uint16_t u16ValueForKey (const std::string & inKey, const uint16_t inDefault = 0) const;
56  NTV2StringSet keys (void) const;
57  size_t largestKeySize (void) const;
58  size_t largestValueSize (void) const;
59  std::ostream & Print (std::ostream & oss, const bool inCompact = true) const;
60 
65  inline void clear (void) {mDict.clear();}
67  inline bool insert (const std::string & inKey, const std::string & inValue) {mDict[inKey] = inValue; return true;}
68  inline size_t erase (const std::string & inKey) {return mDict.erase(inKey);}
69  size_t UpdateFrom (const NTV2Dictionary & inDict);
70  size_t AddFrom (const NTV2Dictionary & inDict);
71 
73  protected:
74  typedef std::map<std::string, std::string> Dict;
75  typedef Dict::const_iterator DictConstIter;
76 
77  private:
78  Dict mDict;
79 }; // NTV2Dictionary
80 
81 typedef NTV2Dictionary NTV2Dict;
82 typedef NTV2Dictionary NTV2ConnectParams;
83 typedef NTV2Dictionary NTV2ConfigParams;
84 typedef std::pair<std::string, std::string> NTV2DictionaryEntry, NTV2DictEntry, NTV2ConnectParam;
85 
86 inline std::ostream & operator << (std::ostream & oss, const NTV2Dictionary & inDict) {return inDict.Print(oss);}
87 
93 class AJAExport NTV2DeviceSpecParser
94 {
95  public:
96  static bool IsSupportedScheme (const std::string & inScheme);
97 
98  public:
99  NTV2DeviceSpecParser (const std::string inSpec = "");
100  void Reset (const std::string inSpec = "");
101  inline const std::string & DeviceSpec (void) const {return mSpec;}
102  inline bool HasDeviceSpec (void) const {return !DeviceSpec().empty();}
103  inline bool Successful (void) const {return !Failed();}
104  inline bool Failed (void) const {return DeviceSpec().empty() ? true : HasErrors();}
105  inline bool HasScheme (void) const {return HasResult(kConnectParamScheme);}
106  inline std::string Scheme (void) const {return Result(kConnectParamScheme);}
107  inline bool IsLocalDevice (void) const {return Scheme() == kLegalSchemeNTV2Local || Scheme() == kLegalSchemeNTV2;}
108  inline size_t ErrorCount (void) const {return mErrors.size();}
109  inline bool HasErrors (void) const {return ErrorCount() > 0;}
110  inline std::string Error (const size_t inIndex = 0) const {if (inIndex < mErrors.size()) return mErrors.at(inIndex); return "";}
111  inline NTV2StringList Errors (void) const {return mErrors;}
112  inline const NTV2ConnectParams & Results (void) const {return mResult;}
113  inline bool HasResult (const std::string & inKey) const {return mResult.hasKey(inKey);}
114  std::string Result (const std::string & inKey) const {return mResult.valueForKey(inKey);}
115  std::string Resource (const bool inStripLeadSlash = true) const;
116  std::ostream & PrintErrors (std::ostream & oss) const;
117  std::ostream & Print (std::ostream & oss, const bool inDumpResults = false) const;
118  std::string InfoString (void) const;
119  uint64_t DeviceSerial (void) const;
120  inline std::string DeviceModel (void) const {return Result(kConnectParamDevModel);}
121  NTV2DeviceID DeviceID (void) const;
122  UWord DeviceIndex (void) const;
123  inline const NTV2Dictionary & QueryParams (void) const {return mQueryParams;}
124  inline std::string QueryParam (const std::string & inKey) const {return mQueryParams.valueForKey(inKey);}
125  #if defined(_DEBUG)
126  static void test (void);
127  #endif // defined(_DEBUG)
128 
129  private:
130  void Parse (void);
131  bool ParseHexNumber (size_t & pos, std::string & outToken);
132  bool ParseDecNumber (size_t & pos, std::string & outToken);
133  bool ParseAlphaNumeric (size_t & pos, std::string & outToken, const std::string & inOtherChars = ""); // A run of letters and/or decimal digits and/or other chars
134  bool ParseScheme (size_t & pos, std::string & outToken); // An alphanumeric name followed by "://"
135  bool ParseSerialNum (size_t & pos, std::string & outToken); // An 8 or 9 character alphanumeric name or a 64-bit hex number
136  bool ParseDeviceID (size_t & pos, std::string & outToken); // An 32-bit hex number that matches a known NTV2DeviceID
137  bool ParseModelName (size_t & pos, std::string & outToken); // An alphanumeric name that matches a known device model name
138  bool ParseDNSName (size_t & pos, std::string & outDNSName); // A domain name: one or more alphanumeric names separated with '.'
139  bool ParseIPv4Address (size_t & pos, std::string & outIPv4); // Exactly four decimal numbers, each no greater than 255, separated with '.'
140  bool ParseHostAddressAndPortNumber (size_t & pos, std::string & outAddr, std::string & outPort); // A host name or IPv4 address with an optional port number
141  bool ParseResourcePath (size_t & pos, std::string & outRsrc); // One or more '/'-separated alphanumeric names
142  bool ParseParamAssignment (size_t & pos, std::string & outKey, std::string & outValue); // An alphanumeric key optionally followed by '=' optionally followed by URL-encoded value string
143  bool ParseQuery (size_t & pos, NTV2Dictionary & outParams); // Starts with '?' one or more '&'-separated param assignments
144  inline int LargestResultKey (void) const {return int(mResult.largestKeySize());}
145  inline int LargestResultValue (void) const {return int(mResult.largestValueSize());}
146  inline char CharAt (const size_t inPos) {return inPos < mSpec.length() ? mSpec.at(inPos) : 0;}
147  inline size_t SpecLength (void) const {return mSpec.length();}
148  inline size_t CurrentPosition (void) const {return mPos;}
149  inline void AddError (const std::string & inError) {mErrors.push_back(inError);}
150  static bool IsUpperLetter (const char inChar);
151  static bool IsLowerLetter (const char inChar);
152  static bool IsLetter (const char inChar, const bool inIncludeUnderscore = false);
153  static bool IsDecimalDigit (const char inChar);
154  static bool IsHexDigit (const char inChar);
155  static bool IsLegalSerialNumChar (const char inChar);
156 
157  private:
158  std::string mSpec;
159  NTV2StringList mErrors;
160  NTV2ConnectParams mResult;
161  NTV2Dictionary mQueryParams;
162  size_t mPos;
163 }; // NTV2DeviceSpecParser
164 
165 
176 class AJAExport NTV2RPCClientAPI
177 {
178  public:
179  static NTV2RPCClientAPI * CreateClient (const NTV2ConnectParams & inParams);
180 
181  public:
185  virtual std::string HostName (void) const {return ConnectParam(kConnectParamHost);}
187  virtual std::string Name (void) const {return "";}
188  virtual std::string Description (void) const;
189  virtual std::ostream & Print (std::ostream & oss) const;
191 
195  virtual bool NTV2Connect (void);
197  virtual bool NTV2Disconnect (void);
198  virtual bool IsConnected (void) const {return false;}
199 
204  virtual const NTV2ConnectParams & ConnectParams (void) const {return mConnectParams;}
206  virtual bool HasConnectParam (const std::string & inParam) const {return mConnectParams.hasKey(inParam);}
207  virtual std::string ConnectParam (const std::string & inParam) const {return mConnectParams.valueForKey(inParam);}
208  virtual bool ConnectHasScheme (void) const {return HasConnectParam(kConnectParamScheme);}
209  virtual bool SetConnectParams (const NTV2ConnectParams & inNewParams, const bool inAugment = false);
210 
215  virtual bool NTV2ReadRegisterRemote (const ULWord regNum, ULWord & outRegValue, const ULWord regMask, const ULWord regShift);
217  virtual bool NTV2WriteRegisterRemote (const ULWord regNum, const ULWord regValue, const ULWord regMask, const ULWord regShift);
218  virtual bool NTV2AutoCirculateRemote (AUTOCIRCULATE_DATA & autoCircData);
219  virtual bool NTV2WaitForInterruptRemote (const INTERRUPT_ENUMS eInterrupt, const ULWord timeOutMs);
220  virtual bool NTV2DMATransferRemote (const NTV2DMAEngine inDMAEngine, const bool inIsRead,
221  const ULWord inFrameNumber, NTV2Buffer & inOutBuffer,
222  const ULWord inCardOffsetBytes, const ULWord inNumSegments,
223  const ULWord inSegmentHostPitch, const ULWord inSegmentCardPitch,
224  const bool inSynchronous);
225  virtual bool NTV2MessageRemote (NTV2_HEADER * pInMessage);
227 
231  virtual bool NTV2GetBoolParamRemote (const ULWord inParamID, ULWord & outValue); // New in SDK 17.0
233  virtual bool NTV2GetNumericParamRemote (const ULWord inParamID, ULWord & outValue); // New in SDK 17.0
234  virtual bool NTV2GetSupportedRemote (const ULWord inEnumsID, ULWordSet & outSupported); // New in SDK 17.0
236 
250  virtual bool NTV2QueryDevices (NTV2StringList & outDeviceInfos) {outDeviceInfos.clear(); return true;}
251 
252  NTV2RPCClientAPI (const NTV2ConnectParams & inParams);
253  virtual ~NTV2RPCClientAPI();
254 
255  #if !defined(NTV2_DEPRECATE_16_3) // These functions are going away
256  virtual bool NTV2DriverGetBitFileInformationRemote (BITFILE_INFO_STRUCT & bitFileInfo, const NTV2BitFileType bitFileType);
257  virtual bool NTV2DriverGetBuildInformationRemote (BUILD_INFO_STRUCT & buildInfo);
258  virtual bool NTV2DownloadTestPatternRemote (const NTV2Channel channel, const NTV2PixelFormat testPatternFBF,
259  const UWord signalMask, const bool testPatDMAEnb, const ULWord testPatNum);
260  virtual bool NTV2ReadRegisterMultiRemote (const ULWord numRegs, ULWord & outFailedRegNum, NTV2RegInfo outRegs[]);
261  virtual bool NTV2GetDriverVersionRemote (ULWord & outDriverVersion);
262  #endif // !defined(NTV2_DEPRECATE_16_3)
263 
264  protected:
265  virtual bool NTV2OpenRemote (void);
266  virtual bool NTV2CloseRemote (void);
267 
268  protected:
269  NTV2ConnectParams mConnectParams;
270  uint32_t mSpare[1024];
271 }; // NTV2RPCClientAPI
272 
273 typedef NTV2RPCClientAPI NTV2RPCAPI;
274 
275 inline std::ostream & operator << (std::ostream & oss, const NTV2RPCClientAPI & inObj) {return inObj.Print(oss);}
276 
281 class AJAExport NTV2RPCServerAPI
282 {
283  public:
291  static NTV2RPCServerAPI * CreateServer (const NTV2ConfigParams & inParams);
292 
301  static NTV2RPCServerAPI * CreateServer (const std::string & inURL);
302 
303  public:
307  virtual std::ostream & Print (std::ostream & oss) const;
310 
314  virtual const NTV2ConfigParams & ConfigParams (void) const {return mConfigParams;}
316  virtual bool HasConfigParam (const std::string & inParam) const {return mConfigParams.hasKey(inParam);}
317  virtual std::string ConfigParam (const std::string & inParam) const {return mConfigParams.valueForKey(inParam);}
318  virtual bool SetConfigParams (const NTV2ConfigParams & inNewParams, const bool inAugment = false);
319 
324  virtual void RunServer (void);
326 
328  protected:
329  NTV2RPCServerAPI (const NTV2ConnectParams & inParams);
330  virtual ~NTV2RPCServerAPI();
331 
332  protected:
333  NTV2ConfigParams mConfigParams;
334  uint32_t mSpare[1024];
335 }; // NTV2RPCServerAPI
336 
337 inline std::ostream & operator << (std::ostream & oss, const NTV2RPCServerAPI & inObj) {return inObj.Print(oss);}
338 
344 extern "C"
345 {
353  typedef NTV2RPCClientAPI* (*fpCreateClient) (void * /*pInDLLHandle*/, const NTV2ConnectParams & /*inParams*/, const uint32_t /*inHostSDKVersion*/);
354 
363  typedef NTV2RPCServerAPI* (*fpCreateServer) (void * /*pInDLLHandle*/, const NTV2ConfigParams & /*inParams*/, const uint32_t /*inHostSDKVersion*/);
364 
365  #if !defined(NTV2_DEPRECATE_16_3) // Don't use these functions going forward
366  typedef NTV2RPCAPI* (*fpCreateNTV2SoftwareDevice) (void * /*pInDLLHandle*/, const std::string & /*inQueryStr*/, const uint32_t /*inHostSDKVersion*/);
367  #endif // !defined(NTV2_DEPRECATE_16_3)
368 }
369 
370 #endif // NTV2NUBACCESS_H
NTV2ConfigParams
NTV2Dictionary NTV2ConfigParams
A dictionary of parameters used to configure an RPC server.
Definition: ntv2nubaccess.h:83
INTERRUPT_ENUMS
enum _INTERRUPT_ENUMS_ INTERRUPT_ENUMS
BUILD_INFO_STRUCT
Definition: ntv2publicinterface.h:4887
NTV2DeviceIDSerialPair
std::pair< NTV2DeviceID, ULWord64 > NTV2DeviceIDSerialPair
Identifies a device by its NTV2DeviceID and serial number.
Definition: ntv2nubaccess.h:17
NTV2StringSet
std::set< std::string > NTV2StringSet
Definition: ntv2utils.h:1137
kConnectParamResource
static const std::string kConnectParamResource("ResourcePath")
Resource path – everything past URL [scheme://host[:port]/], excluding [?query].
NTV2Channel
NTV2Channel
These enum values are mostly used to identify a specific Frame Store. They're also commonly used to i...
Definition: ntv2enums.h:1305
NTV2Buffer
A generic user-space buffer object that has an address and a length. Used most often to share an arbi...
Definition: ntv2publicinterface.h:5967
kConnectParamDevModel
static const std::string kConnectParamDevModel("DeviceModel")
First device of this model (e.g. 'kona4')
NTV2RPCServerAPI
Base class of objects that can serve device operation RPCs with NTV2RPCClientAPI instances.
Definition: ntv2nubaccess.h:281
NTV2DeviceIDSerialPairsConstIter
NTV2DeviceIDSerialPairs::const_iterator NTV2DeviceIDSerialPairsConstIter
Definition: ntv2nubaccess.h:20
NTV2Dict
NTV2Dictionary NTV2Dict
Definition: ntv2nubaccess.h:81
NTV2DeviceID
NTV2DeviceID
Identifies a specific AJA NTV2 device model number. The NTV2DeviceID is actually the PROM part number...
Definition: ntv2enums.h:20
NTV2FrameBufferFormat
NTV2FrameBufferFormat
Identifies a particular video frame buffer format. See Device Frame Buffer Formats for details.
Definition: ntv2enums.h:207
NTV2Dictionary::Print
std::ostream & Print(std::ostream &oss, const bool inCompact=true) const
Prints human-readable representation to ostream.
Definition: ntv2nubaccess.cpp:98
NTV2RPCClientAPI::mConnectParams
NTV2ConnectParams mConnectParams
Copy of connection parameters passed in to NTV2Connect.
Definition: ntv2nubaccess.h:269
kConnectParamDevID
static const std::string kConnectParamDevID("DeviceID")
First device having this ID (e.g. '0x10518400')
NTV2DeviceSpecParser::DeviceModel
std::string DeviceModel(void) const
Definition: ntv2nubaccess.h:120
NTV2RPCAPI
NTV2RPCClientAPI NTV2RPCAPI
Definition: ntv2nubaccess.h:273
NTV2DMAEngine
NTV2DMAEngine
Definition: ntv2enums.h:1801
NTV2RPCClientAPI::NTV2QueryDevices
virtual bool NTV2QueryDevices(NTV2StringList &outDeviceInfos)
Queries the devices that are accessible on the remote host.
Definition: ntv2nubaccess.h:250
kConnectParamDevIndex
static const std::string kConnectParamDevIndex("DeviceIndex")
Device having this index number.
ULWordSet
std::set< ULWord > ULWordSet
A collection of unique ULWord (uint32_t) values.
Definition: ntv2publicinterface.h:53
ULWord
uint32_t ULWord
Definition: ajatypes.h:246
NTV2ConnectParams
NTV2Dictionary NTV2ConnectParams
A dictionary of parameters used to connect to remote/fake devices.
Definition: ntv2nubaccess.h:82
NTV2BitFileType
NTV2BitFileType
Definition: ntv2enums.h:3269
NTV2DeviceIDSerialPairs
std::vector< NTV2DeviceIDSerialPair > NTV2DeviceIDSerialPairs
An ordered sequence of NTV2DeviceIDSerialPairs.
Definition: ntv2nubaccess.h:18
NTV2RPCServerAPI::Print
virtual std::ostream & Print(std::ostream &oss) const
Definition: ntv2nubaccess.cpp:1146
kConnectParamHost
static const std::string kConnectParamHost("Host")
DNS name, IPv4 or sw device DLL name.
NTV2_HEADER
All new NTV2 structs start with this common header.
Definition: ntv2publicinterface.h:6899
kConnectParamQuery
static const std::string kConnectParamQuery("Query")
Query – everything past '?' in URL.
UWord
uint16_t UWord
Definition: ajatypes.h:244
kFuncNameCreateServer
static const std::string kFuncNameCreateServer("CreateServer")
Create an NTV2RPCServerAPI instance.
ntv2utils.h
Declares numerous NTV2 utility functions.
kConnectParamDevSerial
static const std::string kConnectParamDevSerial("DeviceSerial")
Device with this serial number.
NTV2RPCServerAPI::mConfigParams
NTV2ConfigParams mConfigParams
Copy of config params passed in to my constructor.
Definition: ntv2nubaccess.h:333
NTV2Dictionary::DictConstIter
Dict::const_iterator DictConstIter
Definition: ntv2nubaccess.h:75
kFuncNameCreateClient
static const std::string kFuncNameCreateClient("CreateClient")
Create an NTV2RPCClientAPI instance.
NTV2StringList
std::vector< std::string > NTV2StringList
Definition: ntv2utils.h:1134
NTV2DeviceSpecParser
One-stop shop for parsing device specifications. (New in SDK 16.3) I do very little in the way of val...
Definition: ntv2nubaccess.h:93
NTV2DictEntry
std::pair< std::string, std::string > NTV2DictEntry
Definition: ntv2nubaccess.h:84
NTV2DictionaryEntry
std::pair< std::string, std::string > NTV2DictionaryEntry
Definition: ntv2nubaccess.h:84
NTV2ConnectParam
std::pair< std::string, std::string > NTV2ConnectParam
A parameter used to connect to remote/fake devices.
Definition: ntv2nubaccess.h:84
AJAExport
#define AJAExport
Definition: export.h:33
true
#define true
Definition: ntv2devicefeatures.h:26
NTV2DeviceIDSerialPairsIter
NTV2DeviceIDSerialPairs::iterator NTV2DeviceIDSerialPairsIter
Definition: ntv2nubaccess.h:19
kLegalSchemeNTV2Local
static const std::string kLegalSchemeNTV2Local("ntv2local")
NTV2RPCClientAPI::Print
virtual std::ostream & Print(std::ostream &oss) const
Definition: ntv2nubaccess.cpp:872
kLegalSchemeNTV2
static const std::string kLegalSchemeNTV2("ntv2")
NTV2RPCClientAPI
Base class of objects that can connect to, and operate remote or fake devices. I have three general A...
Definition: ntv2nubaccess.h:176
kConnectParamScheme
static const std::string kConnectParamScheme("Scheme")
URL scheme.
NTV2Dictionary::valueForKey
std::string valueForKey(const std::string &inKey) const
Definition: ntv2nubaccess.cpp:54
kConnectParamPort
static const std::string kConnectParamPort("Port")
Port number (optional)
NTV2Dictionary
A simple set of zero or more key/value pairs. (New in SDK 16.3)
Definition: ntv2nubaccess.h:44
NTV2Dictionary::Dict
std::map< std::string, std::string > Dict
Definition: ntv2nubaccess.h:74
BITFILE_INFO_STRUCT
Definition: ntv2publicinterface.h:4772
NTV2RegInfo
Everything needed to call CNTV2Card::ReadRegister or CNTV2Card::WriteRegister functions.
Definition: ntv2publicinterface.h:3900
AUTOCIRCULATE_DATA
Definition: ntv2publicinterface.h:4338
operator<<
std::ostream & operator<<(std::ostream &oss, const NTV2Dictionary &inDict)
Definition: ntv2nubaccess.h:86