OnixS C++ FIX Engine  4.2.0
API Documentation
EngineSettings.h
Go to the documentation of this file.
1 /*
2 * Copyright Onix Solutions Limited [OnixS]. All rights reserved.
3 *
4 * This software owned by Onix Solutions Limited [OnixS] and is protected by copyright law
5 * and international copyright treaties.
6 *
7 * Access to and use of the software is governed by the terms of the applicable OnixS Software
8 * Services Agreement (the Agreement) and Customer end user license agreements granting
9 * a non-assignable, non-transferable and non-exclusive license to use the software
10 * for it's own data processing purposes under the terms defined in the Agreement.
11 *
12 * Except as otherwise granted within the terms of the Agreement, copying or reproduction of any part
13 * of this source code or associated reference material to any other location for further reproduction
14 * or redistribution, and any amendments to this copyright notice, are expressly prohibited.
15 *
16 * Any reproduction or redistribution for sale or hiring of the Software not in accordance with
17 * the terms of the Agreement is a violation of copyright law.
18 */
19 
20 #pragma once
21 
22 #include <vector>
23 #include <string>
24 
26 
27 namespace OnixS {
28 namespace System {
29 class ISettings;
30 }
31 }
32 
33 namespace OnixS {
34 namespace FIX {
35 class Engine;
36 
37 /// Listen ports.
38 typedef std::vector<int> ListenPorts;
39 
40 /// Local interfaces
41 typedef std::string LocalNetworkInterface;
42 typedef std::vector<LocalNetworkInterface> LocalNetworkInterfaces;
43 
44 /// FIX Engine settings.
46 {
47 public:
48  /// Constructor.
50 
51  /// Constructor to create the EngineSettings from a Configuration string.
52  explicit EngineSettings(const std::string & configuration);
53 
54  /// Copy constructor.
56 
57  /// Destructor.
58  ~EngineSettings();
59 
60  /// Assignment.
61  EngineSettings & operator = (const EngineSettings &);
62 
63  /// Option to create the FIX Engine log file.
64  void createEngineLogFile(bool value);
65 
66  /// Option to create the FIX Engine log file.
67  bool createEngineLogFile() const;
68 
69  /// Specifies the path(s) to the XML file(s) with the description of the FIX Dictionary(s).
70  ///
71  /// @note More than one file could be specified. Symbol '|' is used as the file name delimiter.
72  void dictionaryFile(const std::string & value);
73 
74  /// Returns the path to the XML file with the description of the FIX Dictionary(s).
75  const std::string & dictionaryFile() const;
76 
77  /// Specifies the plain text string with description of FIX dialect.
78  void dialectString(const std::string & value);
79 
80  /// Returns The string contains the plain text string with the description of the FIX dialect.
81  const std::string & dialectString() const;
82 
83  /// FIX Engine listens on this port for incoming "plain text" connections.
84  ///
85  /// @note If '0' then only session-initiators can be created.
86  /// @note If '-1' then the telecommunication level is disabled and only message parsing/assembling can be used.
87  void listenPort(int value);
88 
89  /// FIX Engine listens on this port for incoming "plain text" connections.
90  ///
91  /// @note If '0' then only session-initiators can be created.
92  /// @note If '-1' then the telecommunication level is disabled and only message parsing/assembling can be used.
93  int listenPort() const;
94 
95  /// Set listen ports.
96  void listenPorts(const ListenPorts & value);
97 
98  /// Returns listen ports.
99  const ListenPorts & listenPorts() const;
100 
101  /// FIX Engine listens on these local interfaces for incoming "plain text" connections.
102  const LocalNetworkInterfaces & localNetworkInterface() const;
103 
104  /// Sets local interfaces where engine listen for incoming connections.
105  /// Each local interface specification could specify local IP address and port. For instance "localhost" and "192.168.0.1:4501" are valid values. When
106  /// a local interface specification contains the same port as specified at listenPort settings the listening appears only on the interface and port specified
107  /// at localInterface setting.
108  /// @note At least single listen port have to be specified to make engine able to use this setting.
109  void localNetworkInterface(const LocalNetworkInterfaces &);
110 
111  /// Sets local interface where engine listen for incoming connections.
112  /// Each local interface specification could specify local IP address and port. For instance "localhost" and "192.168.0.1:4501" are valid values. When
113  /// a local interface specification contains the same port as specified at listenPort settings the listening appears only on the interface and port specified
114  /// at localInterface setting.
115  /// @note At least single listen port have to be specified to make engine able to use this setting.
116  void localNetworkInterface(const LocalNetworkInterface &);
117 
118  /// Returns the default mode for outbound and incoming connections.
119  ConnectionMode::Enum connectionMode() const;
120 
121  /// Sets the default mode for outbound and incoming connections.
122  void connectionMode(ConnectionMode::Enum value);
123 
124  /// Sets thread pool size.
125  void threadPoolSize(int size);
126 
127  /// Returns thread pool size.
128  int threadPoolSize() const;
129 
130  /// Specifies the path to the license file.
131  ///
132  /// @deprecated This method is deprecated, OnixS::FIX::EngineSettings::licenseStore(const std::string&) should be used instead.
133  void licenseFile(const std::string & value);
134 
135  /// Returns the path to the license file.
136  ///
137  /// @deprecated This method is deprecated, OnixS::FIX::EngineSettings::licenseStore() should be used instead.
138  const std::string & licenseFile() const;
139 
140  /// Specifies the path to the license directory.
141  ///
142  /// @note More than one license store could be specified. Symbol '|' is used as the license store delimiter.
143  void licenseStore(const std::string & value);
144 
145  /// Returns the path to the license directory.
146  const std::string & licenseStore() const;
147 
148  /// Specifies the string of license content.
149  void licenseString(const std::string & value);
150 
151  /// Returns the string of license content.
152  const std::string & licenseString() const;
153 
154  /// Returns the number of days to alert before the license expiration.
155  unsigned licenseAlertingDaysBeforeExpiration();
156 
157  /// Sets the number of days to alert before the license expiration.
158  /// If the amount of remaining license days is less or equal to this number
159  /// then the warning will be reported to the FIX Engine's log and IEngineListener::onWarning callback will be invoked.
160  /// The verification is performed during the following events: FIX Engine initialization, Session::logonAsAcceptor and Session::logonAsInitiator calls.
161  void licenseAlertingDaysBeforeExpiration(unsigned value);
162 
163  /// Inbound and outbound messages, session's state data and the FIX Engine log file (FixEngineLog.txt) are stored in this directory.
164  void logDirectory(const std::string & value);
165 
166  /// Inbound and outbound messages, session's state data and the FIX Engine log file (FixEngineLog.txt) are stored in this directory.
167  const std::string & logDirectory() const;
168 
169  /// Returns the FIX Engine log file name
170  const std::string & logFileName() const;
171 
172  /// Sets the FIX Engine log file name
173  void logFileName(const std::string & value);
174 
175  /// Returns 'true' if inbound messages are logged, otherwise - 'false'.
176  bool logInboundMessages() const;
177 
178  /// Option to log inbound messages.
179  void logInboundMessages(bool value);
180 
181  /// Returns 'true' if outbound messages are logged, otherwise - 'false'.
182  bool logOutboundMessages() const;
183 
184  /// Option to log outbound messages.
185  void logOutboundMessages(bool value);
186 
187  /// Returns 'true' if outbound messages are logged before sending, otherwise - 'false'.
188  bool logBeforeSending() const;
189 
190  /// Option to switch on/off logging of outbound messages before/after sending.
191  void logBeforeSending(bool value);
192 
193  /// Gets the usage of local time in FIX Engine events and log files.
194  bool localTimeUsage() const;
195 
196  /// Specifies the usage of local time in FIX Engine events and log files.
197  /// @param value If it is true - local time usage, if it is false - UTC time usage.
198  void localTimeUsage(bool value);
199 
200  /// Option to process the DeliverToCompID (tag 128) flag.
201  void processDeliverToCompId(bool value);
202 
203  /// Option to process the DeliverToCompID (tag 128) flag.
204  bool processDeliverToCompId() const;
205 
206  /// The reasonable transmission time as % from HeartBtInt value.
207  ///
208  /// When either end of the connection has not received any data for (HeartBtInt * (100 + ReasonableTransmissionTime)/100) seconds,
209  /// it will transmit a Test Request message.
210  ///
211  /// If there is still no Heartbeat message received after (HeartBtInt * (100 + ReasonableTransmissionTime)/100) seconds
212  /// then the connection should be considered lost and corrective action be initiated.
213  ///
214  /// @see If you need to change this option for separate session, please use
215  /// OnixS::FIX::Session::setReasonableTransmissionTime(int).
216  void reasonableTransmissionTime(int value);
217 
218  /// The reasonable transmission time as % from HeartBtInt value.
219  ///
220  /// When either end of the connection has not received any data for (HeartBtInt * (100 + ReasonableTransmissionTime)/100) seconds,
221  /// it will transmit a Test Request message.
222  ///
223  /// If there is still no Heartbeat message received after (HeartBtInt * (100 + ReasonableTransmissionTime)/100) seconds
224  /// then the connection should be considered lost and corrective action be initiated.
225  ///
226  /// @see You also can get value of this option for separate session using
227  /// OnixS::FIX::Session::getReasonableTransmissionTime().
228  int reasonableTransmissionTime() const;
229 
230  /// Sets the number of attempts to restore the telecommunication link.
231  void reconnectAttempts(int value);
232 
233  /// Returns the number of attempts to restore the telecommunication link.
234  int reconnectAttempts() const;
235 
236  /// Sets the time interval between the attempts to restore the telecommunication link (in seconds).
237  void reconnectInterval(int value);
238 
239  /// Returns the time interval between the attempts to restore the telecommunication link (in seconds).
240  int reconnectInterval() const;
241 
242  /// Sets the number of sent messages that are available for resending on counterparty's Resend Request <2> message.
243  void resendingQueueSize(int value);
244 
245  /// Returns the number of sent messages that are available for resending on counterparty's Resend Request <2> message.
246  /// The zero value means that sent messages are not available for resending.
247  /// The value cannot be negative.
248  int resendingQueueSize() const;
249 
250  /// Sets the maximum number of messages to be requested in one Resend Request (MsgType=2) message.
251  void resendRequestMaximumRange(int value);
252 
253  /// Returns the maximum number of messages to be requested in one Resend Request (MsgType=2) message.
254  int resendRequestMaximumRange() const;
255 
256  /// Specifies the usage of the operating system default RecvBuffer size.
257  static const int UseDefaultReceiveBufferSize = -1;
258 
259  /// Returns the size of the TCP buffer allocated to the FIX connection for receiving data.
260  /// If '-1' then the default operating system value is used.
261  int receiveBufferSize() const;
262 
263  /// Sets the size of the TCP buffer allocated to the FIX connection for receiving data.
264  /// If '-1' then the default operating system value is used.
265  void receiveBufferSize(int value);
266 
267  /// Specifies the usage of the operating system default SendBuffer size.
268  static const int UseDefaultSendBufferSize = -1;
269 
270  /// Returns the size of the TCP buffer allocated to the FIX connection for sending data.
271  /// If '-1' then the default operating system value is used.
272  int sendBufferSize() const;
273 
274  /// Sets the size of the TCP buffer allocated to the FIX connection for sending data.
275  /// If '-1' then the default operating system value is used.
276  void sendBufferSize(int value);
277 
278  /// Returns the value of the option to send the Logout message before dropping the telecommunication link in case of Exception during the processing of incoming FIX message.
279  void sendLogoutOnException(bool value);
280 
281  /// Option to send the Logout message before dropping the telecommunication link in case of Exception during the processing of incoming FIX message.
282  bool sendLogoutOnException() const;
283 
284  /// Returns the value of the option to send the Logout message before dropping the telecommunication link in case of an invalid logon attempt.
285  void sendLogoutOnInvalidLogon(bool value);
286 
287  /// Option to send the Logout message before dropping the telecommunication link in case of an invalid logon attempt.
288  bool sendLogoutOnInvalidLogon() const;
289 
290  /// Sets the path to the SSL certificate file in (Privacy Enhanced Mail) Base64 encoded (.pem) format.
291  void sslCertificateFile(const std::string & value);
292 
293  /// Returns the path to the SSL certificate file in (Privacy Enhanced Mail) Base64 encoded (.pem) format.
294  const std::string & sslCertificateFile() const;
295 
296  /// Sets the path to the SSL private key file in (Privacy Enhanced Mail) Base64 encoded (.pem) format.
297  void sslPrivateKeyFile(const std::string & value);
298 
299  /// Returns the path to the SSL private key file in (Privacy Enhanced Mail) Base64 encoded (.pem) format.
300  const std::string & sslPrivateKeyFile() const;
301 
302  /// Set the password to load private keys that are protected by a password.
303  void sslPrivateKeyPassword(const std::string & value);
304 
305  /// Returns the password to load private keys that are protected by a password.
306  const std::string & sslPrivateKeyPassword() const;
307 
308  /// FIX Engine listens on this port for incoming SSL connections.
309  ///
310  /// @note If '0' then only session-initiators can be created.
311  /// @note If '-1' then the telecommunication level is disabled and only message parsing/assembling can be used.
312  void sslListenPort(int value);
313 
314  /// FIX Engine listens on this port for incoming SSL connections.
315  ///
316  /// @note If '0' then only session-initiators can be created.
317  /// @note If '-1' then the telecommunication level is disabled and only message parsing/assembling can be used.
318  int sslListenPort() const;
319 
320  /// Sets SSL listen ports.
321  void sslListenPorts(const ListenPorts & value);
322 
323  /// Returns SSL listen ports.
324  const ListenPorts & sslListenPorts() const;
325 
326  /// FIX Engine listens on these local interfaces for incoming SSL connections.
327  const LocalNetworkInterfaces & sslLocalInterface() const;
328 
329  /// Sets local interfaces where engine listen for incoming SSL connections.
330  /// @note At least single SSL-listen port have to be specified to make engine able to use this setting.
331  void sslLocalInterface(const LocalNetworkInterfaces &);
332 
333  /// Set option to request client certificates and perform the certificate verification.
334  void sslVerifyPeer(bool verify);
335 
336  /// Returns option to request client certificates and perform the certificate verification.
337  bool sslVerifyPeer() const;
338 
339  /// Sets the path to the trusted certification authority certificate file in (Privacy Enhanced Mail) Base64 encoded (.pem) format.
340  void sslCaFile(const std::string & value);
341 
342  /// Returns the path to trusted certification authority certificate file in (Privacy Enhanced Mail) Base64 encoded (.pem) format.
343  const std::string & sslCaFile() const;
344 
345  ///Sets the CPU affinity of the Engine service threads.
346  void serviceThreadAffinity(const OnixS::Threading::CpuIndexes & cpuIndexes);
347 
348  ///Sets the CPU affinity of the Engine service threads.
349  void serviceThreadAffinity(const OnixS::Threading::CpuIndex cpuIndex);
350 
351  ///Returns the CPU affinity of the Engine service threads.
352  const OnixS::Threading::CpuIndexes & serviceThreadAffinity();
353 
354  ///Returns the priority of the Engine service threads.
355  int serviceThreadPriority() const;
356 
357  ///Sets the priority of the Engine service threads.
358  void serviceThreadPriority(int priority);
359 
360  ///Returns the policy of the Engine service threads.
361  int serviceThreadPolicy() const;
362 
363  ///Sets the policy of the Engine service threads.
364  void serviceThreadPolicy(int policy);
365 
366  /// Sets option to improve latency at the expense of message throughput (TCP_NODELAY).
367  void tcpNoDelayOption(bool value);
368 
369  /// Gets option to improve latency at the expense of message throughput (TCP_NODELAY).
370  bool tcpNoDelayOption() const;
371 
372  /// Sets the non-blocking receive spinning timeout (in microseconds) before the receiving thread enters into the blocking wait mode
373  /// @note Should not be greater than 1 sec (minimal Heartbeat interval).
374  void receiveSpinningTimeout(int value);
375 
376  /// Gets the current receive spinning timeout value (in microseconds).
377  int receiveSpinningTimeout() const;
378 
379  /// Sets the send spinning timeout (in microseconds) of the Session::send(..) method to wait for the socket sending buffer availability
380  /// in the spin loop mode before placing the message to the outgoing queue (to be sent later by the sending thread).
381  /// @note Should not be greater than 1 sec (minimal Heartbeat interval).
382  void sendSpinningTimeout(int value);
383 
384  /// Gets the current send spinning timeout value (in microseconds).
385  int sendSpinningTimeout() const;
386 
387  /// Sets message grouping option
388  /// Value 0 means default grouping - the messages will be tried to send ASAP and pending messages (if any) will be grouped till reaching of TCP buffer size.
389  /// Value 1 means the messages will be sent ASAP and never will be grouped.
390  /// Value 2 (or greater) means the messages will be sent ASAP and pending messages will be grouped maximum by 2 (or greater).
391  void messageGrouping(unsigned value);
392 
393  /// Gets message grouping option.
394  unsigned messageGrouping() const;
395 
396  /// Gets segment size for file based session storage.
397  unsigned long long fileBasedStorageSegmentSize() const;
398 
399  /// Sets segment size for file based session storage.
400  /// @param value Maximum size of single segment (single file) of the storage, in bytes.
401  void fileBasedStorageSegmentSize(unsigned long long value);
402 
403  /// Gets the log queue maximum size of the asynchronous session storage.
404  unsigned asyncFileBasedStorageQueueMaxSize() const;
405 
406  /// Sets the log queue maximum size of the asynchronous session storage.
407  void asyncFileBasedStorageQueueMaxSize(unsigned value);
408 
409  ///Sets the CPU affinity of the asynchronous session storage threads.
410  void asyncFileBasedStorageThreadAffinity(const OnixS::Threading::CpuIndexes & cpuIndexes);
411 
412  ///Sets the CPU affinity of the asynchronous session storage threads.
413  void asyncFileBasedStorageThreadAffinity(const OnixS::Threading::CpuIndex cpuIndex);
414 
415  ///Returns the CPU affinity of the asynchronous session storage threads.
416  const OnixS::Threading::CpuIndexes & asyncFileBasedStorageThreadAffinity();
417 
418  /// Gets mode of file based storage integrity errors checking. Valuable only when value of fileBasedStorageSegmentSize != 0.
419  bool ignoreFileBasedStorageIntegrityErrors() const;
420 
421  /// Sets mode of file based storage integrity errors checking. Valuable only when value of fileBasedStorageSegmentSize != 0.
422  /// @param value Mode of checking: true - ignore errors and create new storage, false - throw exception.
423  void ignoreFileBasedStorageIntegrityErrors(bool value);
424 
425  /// Gets option to specify ApplVerID(1128) tag in all FIX messages when a FIX protocol version FIX 5.0 and above is used.
426  bool specifyApplVerIdField() const;
427 
428  /// Sets option to specify ApplVerID(1128) tag in all FIX messages when a FIX protocol version FIX 5.0 and above is used.
429  void specifyApplVerIdField(bool value);
430 
431  /// Gets option to specify the LastMsgSeqNumProcessed (tag=369) field on every message sent. Useful for detecting a backlog with a counterparty.
432  bool specifyLastMsgSeqNumProcessed() const;
433 
434  /// Sets option to specify the LastMsgSeqNumProcessed (tag=369) field on every message sent. Useful for detecting a backlog with a counterparty.
435  void specifyLastMsgSeqNumProcessed(bool value);
436 
437  /// When the message gap is detected the "Resend Request" FIX Message is sent and Session state is changed to "AwaitReplyOnResendRequest".
438  /// By default in this state the incoming new messages (without the PossDupFlag (tag #43) flag) are ignored because we expect them to be re-sent later again with the PossDupFlag flag.
439  ///
440  /// This property allows to change this behavior and report the new messages anyway.
441  ///
442  /// @note In this mode messages could be reported out of the original order: e.g. MsgSeqNum could be: 3 (original), 4 (original), 2 (PossDupFlag='Y'), 3 (PossDupFlag='Y'), 4 (PossDupFlag='Y')
443  /// and some messages could be received two times: first time without PossDupFlag='Y' and second time - with this flag.
444  bool reportNewMessagesWhileWaitingForMissedMessages() const;
445 
446  /// Sets option to report new messages while waiting for missed messages.
447  void reportNewMessagesWhileWaitingForMissedMessages(bool value);
448 
449  /// Gets the expected incoming FIX message size. The value represents an average FIX message size that is expected to be received by the session during the lifetime.
450  /// It is used as a hint for the optimization of the deserialization of large FIX messages with a lot of repeating groups.
451  ///
452  /// @note The large value of the setting can increase the memory consumption by the incoming `Message` object,
453  /// so try to increase the value only in case of a latency degradation of the large incoming FIX messages deserialization.
454  int expectedIncomingMessageSize() const;
455 
456  /// Sets the expected incoming FIX message size.
457  void expectedIncomingMessageSize(int value);
458 
459  /// Get option to validate the presence of unknown FIX messages (messages that do not belong to the message in accordance with the FIX protocol or its FIX Dictionary).
460  bool validateUnknownMessages() const;
461 
462  /// Set option to validate the presence of unknown FIX messages (messages that do not belong to the message in accordance with the FIX protocol or its FIX Dictionary).
463  void validateUnknownMessages(bool);
464 
465  /// Get option to validate the presence of unknown fields (fields that do not belong to the message in accordance with the FIX protocol or its FIX Dictionary.
466  bool validateUnknownFields() const;
467 
468  /// Set option to validate the presence of unknown fields (fields that do not belong to the message in accordance with the FIX protocol or its FIX Dictionary.
469  void validateUnknownFields(bool);
470 
471  /// Get option to validate the presence of required fields in inbound and outbound messages.
472  bool validateRequiredFields() const;
473 
474  /// Set option to validate the presence of required fields in inbound and outbound messages.
475  void validateRequiredFields(bool);
476 
477  /// Get option to validate the field values of FIX messages in accordance with the FIX protocol or its FIX Dictionary.
478  bool validateFieldValues() const;
479 
480  /// Set option to validate the field values of FIX messages in accordance with the FIX protocol or its FIX Dictionary.
481  void validateFieldValues(bool);
482 
483  /// Get option to validate the empty field values of FIX messages in accordance with the FIX protocol or its FIX Dictionary.
484  bool validateEmptyFieldValues() const;
485 
486  /// Set option to validate the empty field values of FIX messages in accordance with the FIX protocol or its FIX Dictionary.
487  void validateEmptyFieldValues(bool);
488 
489  /// Get option to validate the repeating group size of FIX messages in accordance with the FIX protocol or its FIX Dictionary.
490  bool validateRepeatingGroupEntryCount() const;
491 
492  /// Set option to validate the repeating group size of FIX messages in accordance with the FIX protocol or its FIX Dictionary.
493  void validateRepeatingGroupEntryCount(bool);
494 
495  /// Get option to validate the repeating group leading tag of FIX messages in accordance with the FIX protocol or its FIX Dictionary.
496  bool validateRepeatingGroupLeadingTag() const;
497 
498  /// Set option to validate the repeating group leading tag of FIX messages in accordance with the FIX protocol or its FIX Dictionary.
499  void validateRepeatingGroupLeadingTag(bool);
500 
501  /// Get option to validate the duplicated field.
502  bool validateDuplicatedField() const;
503 
504  /// Set option to validate the duplicated field.
505  void validateDuplicatedField(bool);
506 
507 private:
508  friend class Engine;
509 
510  const OnixS::System::ISettings & settings() const;
511 
512  struct Implementation;
513  Implementation * impl;
514 };
515 }
516 }
std::vector< int > ListenPorts
Listen ports.
Definition: Engine.h:34
FIX Engine settings.
std::vector< LocalNetworkInterface > LocalNetworkInterfaces
#define ONIXS_FIXENGINE_API
Definition: ABI.h:45
FIX Engine.
Definition: Engine.h:37
size_t CpuIndex
Logical processors that a thread is allowed to run on (first logical CPU has index 0)...
Definition: Thread.h:31
std::string LocalNetworkInterface
Local interfaces.
std::set< CpuIndex > CpuIndexes
Definition: Thread.h:32