Remote Call Framework 3.0
ClientStub.hpp
Go to the documentation of this file.
1 
2 //******************************************************************************
3 // RCF - Remote Call Framework
4 //
5 // Copyright (c) 2005 - 2018, Delta V Software. All rights reserved.
6 // http://www.deltavsoft.com
7 //
8 // RCF is distributed under dual licenses - closed source or GPL.
9 // Consult your particular license for conditions of use.
10 //
11 // If you have not purchased a commercial license, you are using RCF
12 // under GPL terms.
13 //
14 // Version: 3.0
15 // Contact: support <at> deltavsoft.com
16 //
17 //******************************************************************************
18 
20 
21 #ifndef INCLUDE_RCF_CLIENTSTUB_HPP
22 #define INCLUDE_RCF_CLIENTSTUB_HPP
23 
24 #include <string>
25 #include <vector>
26 #include <memory>
27 
28 #include <RCF/ClientProgress.hpp>
29 #include <RCF/ClientTransport.hpp>
30 #include <RCF/Enums.hpp>
31 #include <RCF/Export.hpp>
32 #include <RCF/RcfClient.hpp>
33 #include <RCF/MethodInvocation.hpp>
34 #include <RCF/SerializationProtocol_Base.hpp>
35 #include <RCF/RcfFwd.hpp>
36 #include <RCF/RecursionLimiter.hpp>
37 #include <RCF/SerializationProtocol.hpp>
38 #include <RCF/Tchar.hpp>
39 
40 #if RCF_FEATURE_FILETRANSFER==1
41 #include <RCF/FileDownload.hpp>
42 #include <RCF/FileUpload.hpp>
43 #endif
44 
45 #ifdef RCF_WINDOWS
46 #include <windows.h>
47 #endif
48 
49 #ifdef RCF_WINDOWS
50 #include <wincred.h>
51 #endif
52 
53 namespace RCF {
54 
55  class RCF_EXPORT CurrentClientStubSentry
56  {
57  public:
58  CurrentClientStubSentry(ClientStub & clientStub);
59  CurrentClientStubSentry(ClientStub * pClientStub);
60  ~CurrentClientStubSentry();
61 
62  private:
63  bool mEnabled;
64  };
65 
67 
69  class RCF_EXPORT ClientStub :
70  public ClientTransportCallback,
71  public std::enable_shared_from_this<ClientStub>
72  {
73 
74  public:
75  ClientStub(const std::string & interfaceName);
76  ClientStub(const std::string & interfaceName, const std::string &serverBindingName);
77  ClientStub(const ClientStub & rhs);
78  ~ClientStub();
79 
80  ClientStub &operator=(const ClientStub & rhs);
81 
82  private:
83  void init(const std::string & interfaceName, const std::string & serverBindingName);
84  void assign(const ClientStub & rhs);
85 
86  // Used internally only.
87  friend class I_RcfClient;
88  void setInterfaceName(const std::string & interfaceName);
89 
90 
91  public:
92 
96 
98 
100  void setServerEndpoint(const Endpoint &endpoint);
101 
103  void setServerEndpoint(EndpointPtr endpointPtr);
104 
106  EndpointPtr getServerEndpoint() const;
107 
109  void setTransport(ClientTransportUniquePtr transport);
110 
112  ClientTransport& getTransport();
113 
115  IpClientTransport & getIpTransport();
116 
118  ClientTransportUniquePtr releaseTransport();
119 
121  TransportType getTransportType();
122 
124  void connect();
125 
127  void disconnect();
128 
130  bool isConnected();
131 
133  FutureConverter<Void> ping();
134 
136 
141  void setAutoReconnect(bool autoReconnect);
142 
144  bool getAutoReconnect() const;
145 
147 
150  void setConnectTimeoutMs(unsigned int connectTimeoutMs);
151 
153  unsigned int getConnectTimeoutMs() const;
154 
156 
157  // Instantiates a client transport for this ClientStub, based on the endpoint type.
158  void instantiateTransport();
159 
160  // Sets the network endpoint at which the RCF server is located.
161  void setEndpoint(const Endpoint &endpoint);
162 
163  // Sets the network endpoint at which the RCF server is located.
164  void setEndpoint(EndpointPtr endpointPtr);
165 
166  // Gets the network endpoint at which the RCF server is located.
167  EndpointPtr getEndpoint() const;
168 
169 
173 
175 
177  void setTransportProtocol(TransportProtocol protocol);
178 
180  TransportProtocol getTransportProtocol() const;
181 
183 
185  void setUserName(const tstring & username);
186 
188  tstring getUserName() const;
189 
191 
193  void setPassword(const tstring & password);
194 
196  tstring getPassword() const;
197 
199 
200  // Only applicable to the Kerberos transport protocol.
201  void setKerberosSpn(const tstring & kerberosSpn);
202 
204  tstring getKerberosSpn() const;
205 
207 
209  void setEnableCompression(bool enableCompression);
210 
212  bool getEnableCompression() const;
213 
215 
216 
219 
221 
223  const std::string & getServantBindingName() const;
224 
226  void setServantBindingName(const std::string &bindingName);
227 
229  const std::string & getInterfaceName();
230 
232  RemoteCallMode getRemoteCallMode() const;
233 
235  void setRemoteCallMode(RemoteCallMode defaultCallingSemantics);
236 
238  void setSerializationProtocol(SerializationProtocol protocol);
239 
241  SerializationProtocol getSerializationProtocol() const;
242 
244  void setEnableSfPointerTracking(bool enable);
245 
247  bool getEnableSfPointerTracking() const;
248 
250 
252  // and the archive version back to that of the RCF server, if the server reports a version mismatch.
254  void setAutoVersioning(bool autoVersioning);
255 
257  bool getAutoVersioning() const;
258 
260 
265  void setRuntimeVersion(std::uint32_t version);
266 
268  std::uint32_t getRuntimeVersion() const;
269 
271 
274  void setArchiveVersion(std::uint32_t version);
275 
277  std::uint32_t getArchiveVersion() const;
278 
280 
282  void setPingBackIntervalMs(int pingBackIntervalMs);
283 
285  int getPingBackIntervalMs();
286 
288 
290  void setRemoteCallTimeoutMs(unsigned int remoteCallTimeoutMs);
291 
293  unsigned int getRemoteCallTimeoutMs() const;
294 
297  void setRemoteCallProgressCallback(
298  RemoteCallProgressCallback progressCallback,
299  std::uint32_t callbackIntervalMs);
300 
301 
303 
304  // Gets the servant binding name to use on the RCF server.
305  const std::string & getServerBindingName() const;
306 
307  // Sets the servant binding name to use on the RCF server.
308  void setServerBindingName(const std::string &bindingName);
309 
310 
311 #if RCF_FEATURE_FILETRANSFER==1
312 
316 
318 
320  void downloadFile(
321  const std::string& downloadId,
322  const Path& downloadPath,
323  FileTransferOptions * pOptions = NULL);
324 
326  void uploadFile(
327  std::string& uploadId,
328  const Path& uploadPath,
329  FileTransferOptions * pOptions = NULL);
330 
332 
333 #endif
334 
335 
340 
342  void setRequestUserData(const std::string & userData);
343 
345  std::string getRequestUserData();
346 
348  void setResponseUserData(const std::string & userData);
349 
351  std::string getResponseUserData();
352 
354 
355  // Gets out-of-band data associated with the next request.
356  ByteBuffer getOutOfBandRequest();
357 
358  // Sets out-of-band data associated with the next request.
359  void setOutofBandRequest(ByteBuffer requestBuffer);
360 
361  // Gets out-of-band data associated with the previous response.
362  ByteBuffer getOutOfBandResponse();
363 
364  // Sets out-of-band data associated with the previous response.
365  void setOutofBandResponse(ByteBuffer responseBuffer);
366 
367 
370 
372 
374  void setHttpProxy(const std::string & httpProxy);
375 
377  std::string getHttpProxy() const;
378 
380  void setHttpProxyPort(int httpProxyPort);
381 
383  int getHttpProxyPort() const;
384 
386  void setHttpProxyUserName(const tstring & proxyUsername);
387 
389  tstring getHttpProxyUserName() const;
390 
392  void setHttpProxyPassword(const tstring & proxyPassword);
393 
395  tstring getHttpProxyPassword() const;
396 
398  void setHttpProxyRealm(const tstring & proxyRealm);
399 
401  tstring getHttpProxyRealm() const;
402 
404 
409 
411  void setCertificate(CertificatePtr certificatePtr);
412 
414  CertificatePtr getCertificate() const;
415 
417  void setCaCertificate(CertificatePtr certificatePtr);
418 
420  CertificatePtr getCaCertificate() const;
421 
423  void setOpenSslCipherSuite(const std::string & cipherSuite);
424 
426  std::string getOpenSslCipherSuite() const;
427 
429  void setEnableSchannelCertificateValidation(const tstring & peerName);
430 
432  tstring getEnableSchannelCertificateValidation() const;
433 
435  void setCertificateValidationCallback(CertificateValidationCallback certificateValidationCb);
436 
438  const CertificateValidationCallback & getCertificateValidationCallback() const;
439 
441  void setSslImplementation(SslImplementation sslImplementation);
442 
444  SslImplementation getSslImplementation() const;
445 
446 #if RCF_FEATURE_SSPI==1
447 
448  void setSchannelEnabledProtocols(DWORD enabledProtocols);
449  DWORD getSchannelEnabledProtocols() const;
450 
451  void setSchannelContextRequirements(ULONG contextRequirements);
452  ULONG getSchannelContextRequirements() const;
453 
456  PCtxtHandle getTransportSecurityContext() const;
457 
460  PCtxtHandle getTransportProtocolSecurityContext() const;
461 #endif
462 
464 
465 #ifdef RCF_WINDOWS
466  void setWindowsImpersonationToken(HANDLE hToken);
468 
470  HANDLE getWindowsImpersonationToken() const;
471 #endif
472 
473 
478 
480 
482  void enableBatching();
483 
485  void disableBatching(bool flush = true);
486 
488  void flushBatch(unsigned int timeoutMs = 0);
489 
491  void setMaxBatchMessageLength(std::uint32_t maxBatchMessageLength);
492 
494  std::uint32_t getMaxBatchMessageLength();
495 
497  std::uint32_t getBatchesSent();
498 
500  std::uint32_t getMessagesInCurrentBatch();
501 
503 
507 
509 
511  void connectAsync(std::function<void()> onCompletion);
512 
514  bool ready();
515 
517  void waitForReady(std::uint32_t timeoutMs = 0);
518 
520  void cancel();
521 
523  bool hasAsyncException();
524 
526  std::unique_ptr<Exception> getAsyncException();
527 
529 
530 
531  void wait(std::function<void()> onCompletion, std::uint32_t timeoutMs);
532 
533  void setTries(std::size_t tries);
534  std::size_t getTries() const;
535 
536 #if RCF_FEATURE_FILETRANSFER==1
537 
538  // Legacy file transfer API.
539 
540  void setFileProgressCallback(FileProgressCallback fileProgressCb);
541  void setFileProgressCallback() { setFileProgressCallback( FileProgressCallback() ); }
542 
543  void uploadFiles(
544  const std::string & whichFile,
545  std::string & uploadId,
546  std::uint32_t chunkSize,
547  std::uint32_t transferRateBps,
548  std::uint32_t sessionLocalId);
549 
550  void uploadFiles(
551  const FileManifest & whichFile,
552  std::string & uploadId,
553  std::uint32_t chunkSize,
554  std::uint32_t transferRateBps,
555  std::uint32_t sessionLocalId);
556 
557  void downloadFiles(
558  const Path& downloadToPath,
559  FileManifest & manifest,
560  std::uint32_t chunkSize,
561  std::uint32_t transferRateBps,
562  std::uint32_t sessionLocalId,
563  const std::string & downloadId,
564  std::uint64_t startPos = 0,
565  std::uint64_t endPos = -1);
566 
567  std::uint32_t addUploadStream(FileUpload fileStream);
568  void processUploadStreams();
569 
570  std::uint32_t addDownloadStream(FileDownload fileStream);
571 
572  // For testing.
573  void setTransferWindowS(std::uint32_t transferWindowS);
574  std::uint32_t getTransferWindowS();
575 #endif
576 
577 
578  FutureConverter<Void> ping(const CallOptions & callOptions);
579 
580  FutureConverter<Void> doControlMessage(
581  const CallOptions & callOptions,
582  ByteBuffer controlRequest);
583 
584  //**********************************************************************
585 
586  public:
587 
588  std::size_t getPingBackCount();
589  std::uint32_t getPingBackTimeStamp();
590 
591  void clearParameters();
592 
593  SerializationProtocolIn & getSpIn();
594  SerializationProtocolOut & getSpOut();
595 
596  void setAsync(bool async);
597  bool getAsync();
598 
599  void setAsyncException(std::unique_ptr<Exception>);
600 
601  std::uint32_t generatePollingTimeout(std::uint32_t timeoutMs);
602  void onPollingTimeout();
603  void onUiMessage();
604 
605  void setSubRcfClientPtr(RcfClientPtr clientStubPtr);
606  RcfClientPtr getSubRcfClientPtr();
607 
608  void setEnableNativeWstringSerialization(bool enable);
609  bool getEnableNativeWstringSerialization() const;
610 
611  friend class CallOptions;
612 
613  private:
614 
615  friend class FutureConverterBase;
616  friend class FutureImplBase;
617 
618  template<
619  typename R,
620  typename A1,
621  typename A2,
622  typename A3,
623  typename A4,
624  typename A5,
625  typename A6,
626  typename A7,
627  typename A8,
628  typename A9,
629  typename A10,
630  typename A11,
631  typename A12,
632  typename A13,
633  typename A14,
634  typename A15>
635  friend class AllocateClientParameters;
636 
637  template<
638  typename R,
639  typename A1,
640  typename A2,
641  typename A3,
642  typename A4,
643  typename A5,
644  typename A6,
645  typename A7,
646  typename A8,
647  typename A9,
648  typename A10,
649  typename A11,
650  typename A12,
651  typename A13,
652  typename A14,
653  typename A15>
654  friend class ClientParameters;
655 
656  template<typename T>
657  friend class Future;
658 
659  void enrol(
660  I_Future *pFuture);
661 
662  void init(
663  int fnId,
664  RCF::RemoteCallMode rcs);
665 
666  void beginCall();
667 
668  void beginSend();
669 
670  void beginReceive();
671 
672  void call(
673  RCF::RemoteCallMode rcs);
674 
675  void onConnectCompleted(
676  bool alreadyConnected = false);
677 
678  void onRequestTransportFiltersCompleted();
679 
680  void doBatching();
681 
682  void onSendCompleted();
683 
684  void onReceiveCompleted();
685 
686  void onTimerExpired();
687 
688  void onError(
689  const std::exception &e);
690 
691  void setAsyncCallback(
692  std::function<void()> callback);
693 
694  void onException(
695  const Exception & e);
696 
697  void scheduleAmiNotification();
698 
699  void createFilterSequence(std::vector<FilterPtr> & filters);
700 
701  void setConnected(bool connected);
702 
703  virtual bool isClientStub() const;
704 
705 
706 
707  public:
708  // Old-style setting of transport and message filters. Leaving as public for now.
709 
710  // Synchronous transport filter requests.
711  void requestTransportFilters(const std::vector<FilterPtr> &filters);
712  void requestTransportFilters(FilterPtr filterPtr);
713  void requestTransportFilters();
714 
715  void clearTransportFilters();
716 
717  // Asynchronous transport filter requests.
718  void requestTransportFiltersAsync(
719  const std::vector<FilterPtr> & filters,
720  std::function<void()> onCompletion);
721 
722  void requestTransportFiltersAsync(
723  FilterPtr filterPtr,
724  std::function<void()> onCompletion);
725 
726  void setMessageFilters(const std::vector<FilterPtr> &filters);
727  void setMessageFilters();
728  void setMessageFilters(FilterPtr filterPtr);
729 
730  const std::vector<FilterPtr> &getMessageFilters();
731 
732  std::vector<char> & getRetValVec();
733 
734  private:
735 
736  RemoteCallMode mRemoteCallMode;
737  SerializationProtocol mProtocol;
738  std::string mEndpointName;
739  std::string mServerBindingName;
740  std::string mInterfaceName;
741 
742  unsigned int mRemoteCallTimeoutMs;
743  unsigned int mConnectTimeoutMs;
744  bool mAutoReconnect;
745  bool mConnected;
746  std::size_t mTries;
747 
748  EndpointPtr mEndpoint;
749  ClientTransportUniquePtr mTransport;
750 
751  std::vector<FilterPtr> mMessageFilters;
752 
753  RemoteCallProgressCallback mProgressCallback;
754  unsigned int mProgressCallbackIntervalMs = 0;
755 
756 
757  bool mAutoVersioning;
758  std::uint32_t mRuntimeVersion;
759  std::uint32_t mArchiveVersion;
760 
761  bool mEnableSfPointerTracking;
762  bool mEnableNativeWstringSerialization = false;
763 
764  std::vector<I_Future *> mFutures;
765 
766  MethodInvocationRequest mRequest;
767  SerializationProtocolIn mIn;
768  SerializationProtocolOut mOut;
769 
770  bool mAsync;
771  AsyncOpType mAsyncOpType;
772  std::function<void()> mAsyncCallback;
773  std::unique_ptr<Exception> mAsyncException;
774  unsigned int mEndTimeMs;
775  bool mRetry;
776  RemoteCallMode mRcs;
777  ByteBuffer mEncodedByteBuffer;
778  std::vector<ByteBuffer> mEncodedByteBuffers;
779 
780  std::vector<char> mRetValVec;
781  std::vector<char> mParametersVec;
782  I_Parameters * mpParameters;
783 
784  std::uint32_t mPingBackIntervalMs;
785  std::uint32_t mPingBackTimeStamp;
786  std::size_t mPingBackCount;
787 
788  std::uint32_t mNextTimerCallbackMs;
789  std::uint32_t mNextPingBackCheckMs;
790  std::uint32_t mPingBackCheckIntervalMs;
791 
792  MutexPtr mSignalledMutexPtr;
793  ConditionPtr mSignalledConditionPtr;
794  LockPtr mSignalledLockPtr;
795 
796  bool mSignalled;
797 
798  Mutex mSubRcfClientMutex;
799  RcfClientPtr mSubRcfClientPtr;
800 
801  bool mBatchMode;
802  ReallocBufferPtr mBatchBufferPtr;
803  ReallocBuffer mBatchBufferTemp;
804  std::uint32_t mBatchMaxMessageLength;
805  std::uint32_t mBatchCount;
806  std::uint32_t mBatchMessageCount;
807 
808  // Set to true if we need to set the transport protocol without disconnecting.
809  bool mSetTransportProtocol;
810 
811 
812 #if RCF_FEATURE_FILETRANSFER==1
813  FileProgressCallback mFileProgressCb;
814 
815  std::vector<FileUpload> mUploadStreams;
816  std::vector<FileDownload> mDownloadStreams;
817 #endif
818 
819  std::uint32_t mTransferWindowS;
820 
821  RecursionState<int, int> mRecursionState;
822 
823  public:
824 
825  std::string mCurrentCallDesc;
826  bool mCallInProgress;
827 
828 #ifdef RCF_WINDOWS
829  private:
830  std::unique_ptr<HANDLE> mWindowsImpersonationToken;
831 #endif
832 
833  private:
834  std::string mHttpProxy;
835  int mHttpProxyPort;
836  tstring mHttpProxyRealm;
837  TransportProtocol mTransportProtocol;
838  tstring mUsername;
839  tstring mPassword;
840  tstring mHttpProxyUsername;
841  tstring mHttpProxyPassword;
842  tstring mKerberosSpn;
843  bool mEnableCompression;
844 
845  CertificatePtr mCertificatePtr;
846  CertificatePtr mCaCertificatePtr;
847  CertificateValidationCallback mCertificateValidationCb;
848  tstring mSchannelCertificateValidation;
849 
850  std::string mOpenSslCipherSuite;
851 
852  SslImplementation mSslImplementation;
853 
854 #if RCF_FEATURE_SSPI==1
855  DWORD mSchannelEnabledProtocols = 0;
856  ULONG mSchannelContextRequirements = 0;
857 #endif
858 
859 
860  private:
861  void requestTransportFilters_Legacy(const std::vector<FilterPtr> &filters);
862 
863  void requestTransportFiltersAsync_Legacy(
864  const std::vector<FilterPtr> &filters,
865  std::function<void()> onCompletion);
866  };
867 
868  class RCF_EXPORT CallOptions
869  {
870  public:
871  CallOptions();
872  CallOptions(RemoteCallMode rcs);
873  CallOptions(RemoteCallMode rcs, const std::function<void()> & callback);
874  CallOptions(std::function<void()> callback);
875  RemoteCallMode apply(ClientStub &clientStub) const;
876 
877  private:
878  bool mAsync;
879  bool mRcsSpecified;
880  RemoteCallMode mRcs;
881  std::function<void()> mCallback;
882  };
883 
884  class RCF_EXPORT AsyncTwoway : public CallOptions
885  {
886  public:
887  AsyncTwoway(const std::function<void()> & callback);
888  };
889 
890  class RCF_EXPORT AsyncOneway : public CallOptions
891  {
892  public:
893  AsyncOneway(const std::function<void()> & callback);
894  };
895 
896  class RestoreClientTransportGuard
897  {
898  public:
899 
900  RestoreClientTransportGuard(ClientStub &client, ClientStub &clientTemp);
901  ~RestoreClientTransportGuard();
902 
903  private:
904  ClientStub &mClient;
905  ClientStub &mClientTemp;
906  };
907 
908 } // namespace RCF
909 
910 #endif // ! INCLUDE_RCF_CLIENTSTUB_HPP
RCF_FILESYSTEM_NS::path Path
Typedef for standard C++ path type.
Definition: FileSystem.hpp:35
RCF_EXPORT std::uint32_t getArchiveVersion()
Gets the RCF archive version number.
Base class of all RcfClient<> templates.
Definition: RcfClient.hpp:45
std::function< void(const RemoteCallProgressInfo &, RemoteCallAction &)> RemoteCallProgressCallback
Describes a user-provided callback function to be called periodically on the client side...
Definition: RcfFwd.hpp:83
Client side options for downloading and uploading files.
Definition: FileStream.hpp:371
Controls the client side of a RCF connection.
Definition: ClientStub.hpp:69
std::shared_ptr< Endpoint > EndpointPtr
Reference counted wrapper for RCF::Endpoint.
Definition: RcfFwd.hpp:117
std::shared_ptr< Certificate > CertificatePtr
Reference counted wrapper for RCF::Certificate.
Definition: RcfFwd.hpp:108
std::function< void(const FileTransferProgress &)> FileProgressCallback
Describes user-provided callback functions for client-side monitoring of a file transfer (download or...
Definition: RcfFwd.hpp:131
SerializationProtocol
Describes which serialization implementation to use when serializing data structures for a remote cal...
Definition: Enums.hpp:167
std::unique_ptr< ClientTransport > ClientTransportUniquePtr
Unique pointer wrapper for RCF::ClientTransport.
Definition: RcfFwd.hpp:43
Base class for all client transports.
Definition: ClientTransport.hpp:75
std::function< bool(Certificate *)> CertificateValidationCallback
Describes user-provided callback functions for validating a certificate.
Definition: RcfFwd.hpp:114
RemoteCallMode
Remote call mode.
Definition: Enums.hpp:141
Provides the ability for remote calls to be executed asynchronously.
Definition: Future.hpp:51
Base class for all RCF exceptions.
Definition: Exception.hpp:64
RCF_EXPORT void setArchiveVersion(std::uint32_t version)
Sets the RCF archive version number. Applies to all RCF clients and servers within the current proces...
RCF_EXPORT std::uint32_t getRuntimeVersion()
Gets the RCF runtime version number.
SslImplementation
Describes which SSL implementation to use.
Definition: Enums.hpp:85
Utility class used by RCF to determine whether a remote call should be performed synchronously or asy...
Definition: Future.hpp:35
Base class for all network endpoint types.
Definition: Endpoint.hpp:41
Base class for IP-based client transports. Provides IP-related functionality.
Definition: IpClientTransport.hpp:28
Definition: ByteBuffer.hpp:40
TransportProtocol
Describes the transport protocols used by a RCF connection. Transport protocols are layered on top of...
Definition: Enums.hpp:63
Definition: AmiIoHandler.hpp:24
TransportType
Describes the transport types used by a RCF connection.
Definition: Enums.hpp:34
RCF_EXPORT void setRuntimeVersion(std::uint32_t version)
Sets the RCF runtime version number. Applies to all RCF clients and servers within the current proces...
RCF_EXPORT bool init(RcfConfigT *=nullptr)
Reference-counted initialization of RCF library. May be called multiple times (see deinit())...