1 /*****************************************************************************/
2 /* Software Testing Automation Framework (STAF)                              */
3 /* (C) Copyright IBM Corp. 2001                                              */
4 /*                                                                           */
5 /* This software is licensed under the Eclipse Public License (EPL) V1.0.    */
6 /*****************************************************************************/
7 
8 #ifndef STAF_STAF
9 #define STAF_STAF
10 
11 #ifndef STAF_NATIVE_COMPILER
12 #define STAF_INLINE inline
13 #else
14 #define STAF_INLINE
15 #endif
16 
17 #include "STAFOSTypes.h"
18 #include "STAFError.h"
19 #include "STAFDataTypes.h"
20 
21 #ifdef __cplusplus
22 extern "C" {
23 #endif
24 
25 typedef unsigned int STAFHandle_t;
26 typedef unsigned int STAFSyncOption_t;
27 
28 enum STAFSyncOption_e
29 {
30     kSTAFReqSync = 0,
31     kSTAFReqFireAndForget = 1,
32     kSTAFReqQueue = 2,
33     kSTAFReqRetain = 3,
34     kSTAFReqQueueRetain = 4
35 };
36 
37 
38 STAFRC_t STAFRegister(char *processName, STAFHandle_t *handle);
39 STAFRC_t STAFRegisterUTF8(char *processName, STAFHandle_t *handle);
40 STAFRC_t STAFUnRegister(STAFHandle_t handle);
41 STAFRC_t STAFSubmit(STAFHandle_t handle, char *where, char *service,
42                     char *request, unsigned int requestLength,
43                     char **resultPtr, unsigned int *resultLength);
44 STAFRC_t STAFSubmitUTF8(STAFHandle_t handle, char *where,
45                         char *service, char *request,
46                         unsigned int requestLength,
47                         char **resultPtr,
48                         unsigned int *resultLength);
49 STAFRC_t STAFSubmit2(STAFHandle_t handle, STAFSyncOption_t syncOption,
50                      char *where, char *service,
51                      char *request, unsigned int requestLength,
52                      char **resultPtr, unsigned int *resultLength);
53 STAFRC_t STAFSubmit2UTF8(STAFHandle_t handle, STAFSyncOption_t syncOption,
54                          char *where, char *service, char *request,
55                          unsigned int requestLength,
56                          char **resultPtr,
57                          unsigned int *resultLength);
58 
59 STAFRC_t STAFFree(STAFHandle_t handle, char *result);
60 
61 STAFRC_t STAFAddPrivacyDelimiters(STAFStringConst_t data,
62                                   STAFString_t *result);
63 STAFRC_t STAFRemovePrivacyDelimiters(STAFStringConst_t data,
64                                      unsigned int numLevels,
65                                      STAFString_t *result);
66 STAFRC_t STAFMaskPrivateData(STAFStringConst_t data, STAFString_t *result);
67 STAFRC_t STAFEscapePrivacyDelimiters(STAFStringConst_t data,
68                                      STAFString_t *result);
69 
70 #ifdef __cplusplus
71 }
72 
73 #include "STAFString.h"
74 #include "STAFRefPtr.h"
75 
76 // STAFResult - This class contains the results of a STAFSubmit call
77 
78 class STAFResult
79 {
80 public:
81 
82     STAFResult(STAFRC_t theRC = kSTAFOk,
83                const STAFString &theResult = STAFString())
rc(theRC)84         : rc(theRC), result(theResult)
85     { /* Do Nothing */ }
86 
STAFResult(STAFRC_t theRC,const char * data,unsigned int dataLen,STAFString::CodePageType codePageType)87     STAFResult(STAFRC_t theRC, const char *data, unsigned int dataLen,
88                STAFString::CodePageType codePageType)
89         : rc(theRC), result(data, dataLen, codePageType)
90     { /* Do Nothing */ }
91 
STAFResult(STAFRC_t theRC,const char * data,unsigned int dataLen,STAFString::CodePageType codePageType,bool doUnmarshallResult)92     STAFResult(STAFRC_t theRC, const char *data, unsigned int dataLen,
93                STAFString::CodePageType codePageType, bool doUnmarshallResult)
94         : rc(theRC), result(data, dataLen, codePageType)
95     {
96         if (doUnmarshallResult)
97         {
98             resultContext = STAFObject::unmarshall(
99                 result, kSTAFUnmarshallingDefaults);
100             resultObj = resultContext->getRootObject();
101         }
102         else
103         {
104             resultContext = STAFObject::createNone();
105             resultObj = STAFObject::createNone();
106         }
107     }
108 
109     STAFRC_t rc;
110     STAFString result;
111     STAFObjectPtr resultObj;
112     STAFObjectPtr resultContext;
113 };
114 
115 class STAFHandle;
116 typedef STAFRefPtr<STAFResult> STAFResultPtr;
117 typedef STAFRefPtr<STAFHandle> STAFHandlePtr;
118 
119 
120 // STAFHandle - This class is used to interact with STAF.  You obtain a
121 //              STAFHandle via the create() call.
122 
123 class STAFHandle
124 {
125 public:
126 
127     // This is the standard call to create a STAFHandle.  By default, this
128     // STAFHandle object will unregister with STAF when destructed.
129     static STAFRC_t create(const STAFString &name, STAFHandlePtr &handle);
130 
131     // This call is used to create a STAFHandle which uses an existing
132     // STAFHandle_t.  By default, this STAFHandle object will not unregister
133     // with STAF when destructed.
134     static STAFRC_t create(STAFHandle_t handleT, STAFHandlePtr &handle,
135                            bool doUnreg = false);
136 
137     STAFResultPtr submit(const STAFString &where, const STAFString &service,
138                          const STAFString &request,
139                          const STAFSyncOption_t synchOption = kSTAFReqSync);
140 
141     // This returns the colon-length-colon delimited version of a string
142     static STAFString wrapData(const STAFString &data);
143 
144     // This will format a string for you.  See STAFUtilFormatString() in
145     // STAFUtil.h
146     //
147     // Note: DO NOT try to pass STAFString's into the ... portion of this
148     //       function.  The only supported data types are "unsigned int" and
149     //       STAFString_t.  Therefore be sure to call getImpl() on all
150     //       STAFString's before passing them to this method.
151 
152     static STAFString formatString(STAFStringConst_t formatString, ...);
153 
154     // This returns the endpoint without the port (strips @nnnn from the end
155     // of the endpoint, if present)
156     static STAFString stripPortFromEndpoint(const STAFString &endpoint);
157 
158     // This method returns the data with privacy delimiters added.
159     // For example, if pass in "secret", it returns "!!@secret@!!".
160     static STAFString addPrivacyDelimiters(const STAFString &data);
161 
162     // This method removes any privacy delimiters from the data.
163     // For example, if pass in "!!@secret@!!", it returns "secret".
164     static STAFString removePrivacyDelimiters(const STAFString &data,
165                                               unsigned int numLevels = 0);
166 
167     // This method masks any private data indicated by the privacy delimiters
168     // by replacing the private data with asterisks.
169     // For example, if pass in "!!@secret@!!", it returns "************".
170     static STAFString maskPrivateData(const STAFString &data);
171 
172     // This method returns the data with privacy delimiters escaped.
173     // For example, if pass in "!!@secret@!!", it returns "^!!@secret^@!!".
174     static STAFString escapePrivacyDelimiters(const STAFString &data);
175 
getHandle()176     STAFHandle_t getHandle() { return fHandle; }
177 
178     // This call allows you to claim ownership of the underlying STAFHandle_t.
179     // Once this call is made, this STAFHandle object is no longer valid, and
180     // it is your responsibility to unregister the STAFHandle_t with STAF.
181     STAFHandle_t adoptHandle();
182 
getDoUnreg()183     bool getDoUnreg() { return fDoUnreg; }
setDoUnreg(bool doUnreg)184     void setDoUnreg(bool doUnreg) { fDoUnreg = doUnreg; }
185 
getDoUnmarshallResult()186     bool getDoUnmarshallResult() { return fDoUnmarshallResult; }
187 
setDoUnmarshallResult(bool flag)188     void setDoUnmarshallResult(bool flag)
189     {
190         fDoUnmarshallResult = flag;
191     }
192 
193     ~STAFHandle();
194 
195 protected:
196 
STAFHandle(STAFHandle_t handle,bool doUnreg)197     STAFHandle(STAFHandle_t handle, bool doUnreg)
198         : fDoUnreg(doUnreg), fHandle(handle)
199     {
200         fDoUnmarshallResult = true;
201     }
202 
203     bool fDoUnreg;
204     STAFHandle_t fHandle;
205     bool fDoUnmarshallResult;
206 };
207 
208 
209 // Now include inline definitions
210 
211 #ifndef STAF_NATIVE_COMPILER
212 #include "STAFInlImpl.cpp"
213 #endif
214 
215 // End C++ language definitions
216 
217 // End #ifdef __cplusplus
218 
219 #endif
220 
221 #endif
222