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_Util 9 #define STAF_Util 10 11 #include "STAF.h" 12 #include "STAFString.h" 13 #include "STAFProcess.h" 14 #include <stdarg.h> 15 16 #ifdef __cplusplus 17 extern "C" 18 { 19 #endif 20 21 /* Define min and max macros. We've had conflicts using raw min() and max() */ 22 23 #define STAF_MIN(a,b) ((a) <= (b) ? (a) : (b)) 24 #define STAF_MAX(a,b) ((a) >= (b) ? (a) : (b)) 25 26 /* Defines a structure to receive configuration information */ 27 struct STAFConfigInfo 28 { 29 STAFStringConst_t bootDrive; 30 STAFStringConst_t osName; 31 STAFStringConst_t osMajorVersion; 32 STAFStringConst_t osMinorVersion; 33 STAFStringConst_t osRevision; 34 STAFUInt64_t physicalMemory; 35 STAFStringConst_t exePath; 36 STAFStringConst_t lineSeparator; 37 STAFStringConst_t fileSeparator; 38 STAFStringConst_t pathSeparator; 39 STAFStringConst_t commandSeparator; 40 STAFProcessStopMethod_t defaultProcessStopMethod; 41 STAFProcessConsoleMode_t defaultProcessConsoleMode; 42 unsigned int envVarCaseSensitive; /* 0=CaseInsensitive; 1=CaseSensitive */ 43 unsigned int numProcessors; 44 STAFStringConst_t currentDrive; 45 STAFProcessID_t maxPid; // Maximum value for a pid (Process ID) 46 }; 47 48 49 /*********************************************************************/ 50 /* STAFUtilGetConfigInfo - Retrieves OS configuration information */ 51 /* */ 52 /* Accepts: (Out) A pointer to a STAFConfigInfo structure */ 53 /* (Out) A pointer to an error string */ 54 /* (Out) A pointer to an operating system return code */ 55 /* */ 56 /* Returns: 0, if successful */ 57 /* >0, if unsuccessful (*errorBuffer and *osRC will be set) */ 58 /*********************************************************************/ 59 unsigned int STAFUtilGetConfigInfo(struct STAFConfigInfo *configInfo, 60 STAFString_t *errorBuffer, 61 unsigned int *osRC); 62 63 64 /*********************************************************************/ 65 /* STAFUtilGetCurrentProcessCodePage - Obtains a string representing */ 66 /* the current process' code */ 67 /* page */ 68 /* */ 69 /* Accepts: (In) A pointer to the buffer to hold the code page */ 70 /* string (this should be large enough to hold the */ 71 /* largest codepage string for the operating system; */ 72 /* typically 128 bytes should be sufficient) */ 73 /* */ 74 /* Returns: The pointer passed in */ 75 /*********************************************************************/ 76 char *STAFUtilGetCurrentProcessCodePage(char *buffer); 77 78 79 /*********************************************************************/ 80 /* STAFUtilGetPID - Returns the effective Process ID (PID) */ 81 /* */ 82 /* Accepts: Nothing */ 83 /* */ 84 /* Returns: The Process' ID */ 85 /* */ 86 /* Notes : 1) This routine should be used instead of getpid(), as */ 87 /* getpid() behaves strangely in a multi-threaded */ 88 /* environment on Linux */ 89 /*********************************************************************/ 90 STAFProcessID_t STAFUtilGetPID(); 91 92 93 /*********************************************************************/ 94 /* STAFUtilGetSystemMemory - Obtains a piece of system memory */ 95 /* */ 96 /* Accepts: (In) The size of the memory needed */ 97 /* (Out) Pointer to an operating system return code */ 98 /* */ 99 /* Returns: 0, if unsuccessful (*osRC will be set) */ 100 /* >0, if successful (this is the address of the memory) */ 101 /*********************************************************************/ 102 void *STAFUtilGetSystemMemory(unsigned long size, unsigned int *osRC); 103 104 105 /*********************************************************************/ 106 /* STAFUtilFreeSystemMemory - Frees a piece of system memory */ 107 /* */ 108 /* Accepts: (In) The pointer to the system memory to free */ 109 /* */ 110 /* Returns: Nothing */ 111 /*********************************************************************/ 112 void STAFUtilFreeSystemMemory(void *); 113 114 115 /*********************************************************************/ 116 /* STAFUtilSwapUInt - Byte reverses an unsigned int. In other */ 117 /* words, it converts from little-endian or */ 118 /* visa-versa. */ 119 /* */ 120 /* Accepts: (In) The unsigned int to byte reverse */ 121 /* */ 122 /* Returns: The byte-reversed unsigned int */ 123 /*********************************************************************/ 124 unsigned int STAFUtilSwapUInt(unsigned int theUInt); 125 126 127 /*********************************************************************/ 128 /* STAFUtilConvertNativeUIntToLE - Converts an unsigned in the */ 129 /* platform's native format to */ 130 /* little-endian format */ 131 /* */ 132 /* Accepts: (In) The unsigned int to convert to little-endian */ 133 /* */ 134 /* Returns: The little-endian version of the unsigned int */ 135 /*********************************************************************/ 136 unsigned int STAFUtilConvertNativeUIntToLE(unsigned int theUInt); 137 138 139 /*********************************************************************/ 140 /* STAFUtilConvertLEUIntToNative - Converts an unsigned in */ 141 /* little-endian format to the */ 142 /* platform's native format */ 143 /* */ 144 /* Accepts: (In) The unsigned int to convert to little-endian */ 145 /* */ 146 /* Returns: The little-endian version of the unsigned int */ 147 /*********************************************************************/ 148 unsigned int STAFUtilConvertLEUIntToNative(unsigned int theUInt); 149 150 151 /*********************************************************************/ 152 /* STAFUtilIsValidSocket - Determines if a socket descriptor, */ 153 /* received from socket() or accept() is */ 154 /* valid */ 155 /* */ 156 /* Accepts: (In) The socket to check */ 157 /* */ 158 /* Returns: 0, if the socket is invalid */ 159 /* >0, if the socket is valid */ 160 /*********************************************************************/ 161 unsigned int STAFUtilIsValidSocket(STAFSocket_t theSocket); 162 163 164 /*********************************************************************/ 165 /* STAFUtilGetNonInheritableSocket - Provides a new socket that is */ 166 /* a identical to the old socket except the new socket cannot be */ 167 /* inherited by new processes. */ 168 /* */ 169 /* Accepts: (In) The socket to duplicate */ 170 /* (Out) The new socket (with inheritHandle set to FALSE) */ 171 /* (Out) A pointer to an operating system return code */ 172 /* */ 173 /* Returns: 0, if successful */ 174 /* >0, if unsuccessful (*osRC will be set) */ 175 /*********************************************************************/ 176 unsigned int STAFUtilGetNonInheritableSocket(STAFSocket_t oldSocket, 177 STAFSocket_t *newSocket, 178 unsigned int *osRC); 179 180 181 /*********************************************************************/ 182 /* STAFUtilFormatString - Generates a string based on a format */ 183 /* string, ala printf(). This is generally */ 184 /* used to format STAF request strings. */ 185 /* */ 186 /* Accepts: (In) The format string */ 187 /* (Out) A pointer to the output string */ 188 /* (In) All data indicated in the format string */ 189 /* */ 190 /* Returns: Standard return codes */ 191 /* */ 192 /* Notes : 1) The caller is responsible for destructing the */ 193 /* output string */ 194 /*********************************************************************/ 195 /* Valid format string specifiers: */ 196 /* */ 197 /* %d - an unsigned integer */ 198 /* %s - a STAFString_t */ 199 /* %C - a STAFString_t which will be formatted in colon-length-colon */ 200 /* delimited format */ 201 /* %% - a percent sign */ 202 /* */ 203 /* Any other %<char> is simply ignored (and not copied) */ 204 /*********************************************************************/ 205 unsigned int STAFUtilFormatString(STAFStringConst_t formatString, 206 STAFString_t *outputString, ...); 207 208 209 /*********************************************************************/ 210 /* STAFUtilFormatString2 - Generates a string based on a format */ 211 /* string, ala printf(). This is generally */ 212 /* used to format STAF request strings. */ 213 /* */ 214 /* Accepts: (In) The format string */ 215 /* (Out) A pointer to the output string */ 216 /* (In) A variable argument list */ 217 /* */ 218 /* Returns: Standard return codes */ 219 /* */ 220 /* Notes : 1) The caller is responsible for destructing the */ 221 /* output string */ 222 /* 2) Valid format strings are the same as defined for */ 223 /* STAFUtilFormatString() */ 224 /*********************************************************************/ 225 unsigned int STAFUtilFormatString2(STAFStringConst_t formatString, 226 STAFString_t *outputString, va_list args); 227 228 229 /*********************************************************************/ 230 /* STAFUtilCreateTempFile - Creates a 0 length temporary file */ 231 /* */ 232 /* Accepts: (In) A pointer to a string containing the name of the */ 233 /* directory to store the temporary file in */ 234 /* (In) A pointer to a string containing the suffix for */ 235 /* the temporary file name */ 236 /* (In) The request number (used in generating a unique */ 237 /* random seed) */ 238 /* (Out) A pointer to a string containing the name of the */ 239 /* temporary file created */ 240 /* (Out) A pointer to an error string */ 241 /* (Out) A pointer to an operating system return code */ 242 /* */ 243 /* Returns: 0, if successful */ 244 /* >0, if unsuccessful (*errorBuffer and *osRC will be set) */ 245 /* */ 246 /* Notes : 1) The caller is responsible for destructing the output */ 247 /* string containing the name of the temporary file */ 248 /*********************************************************************/ 249 STAFRC_t STAFUtilCreateTempFile(STAFStringConst_t prefix, 250 STAFStringConst_t suffix, 251 unsigned int requestNumber, 252 STAFString_t *tempFileName, 253 STAFString_t *errorBuffer, 254 unsigned int *osRC); 255 256 257 /*********************************************************************/ 258 /* STAFUtilStripPortFromEndpoint - Removes @<Port> from the end of */ 259 /* an endpoint if present. */ 260 /* */ 261 /* Accepts: (In/Out) A pointer to a string containing the endpoint */ 262 /* with format: */ 263 /* [<Interface>://<Machine Identifier>[@<Port>] */ 264 /* (Out) A pointer to a string containing the stripped */ 265 /* endpoint with format: */ 266 /* [<Interface>://<Machine Identifier> */ 267 /* */ 268 /* Returns: 0 */ 269 /* Notes : 1) The caller is responsible for destructing the output */ 270 /* string containing the stripped endpoint */ 271 /*********************************************************************/ 272 STAFRC_t STAFUtilStripPortFromEndpoint(STAFStringConst_t endpoint, 273 STAFString_t *strippedEndpoint); 274 275 276 /*********************************************************************/ 277 /* STAFUtilValidateTrust - Verifies that the actual trust level is */ 278 /* not less than the required trust level. */ 279 /* */ 280 /* Accepts: (In) The actual trust level of the requesting machine */ 281 /* (In) The required trust level for the service request */ 282 /* (In) A pointer to a string containing the name of the */ 283 /* service */ 284 /* (In) A pointer to a string containing the request string*/ 285 /* (In) A pointer to a string containing the name of the */ 286 /* local machine (it's STAF/Config/Machine value) */ 287 /* (In) A pointer to a string containing the endpoint of */ 288 /* the requesting machine */ 289 /* (In) A pointer to a string containing the physical */ 290 /* interface identifier of the requesting machine */ 291 /* (In) A pointer to a string containing the user of the */ 292 /* requesting machine */ 293 /* (Out) A pointer to an error string */ 294 /* */ 295 /* Returns: 0, if successful */ 296 /* 25, if unsuccessful (*errorBuffer will be set) */ 297 /*********************************************************************/ 298 STAFRC_t STAFUtilValidateTrust(unsigned int actualTrustLevel, 299 unsigned int requiredTrustLevel, 300 STAFStringConst_t service, 301 STAFStringConst_t request, 302 STAFStringConst_t localMachine, 303 STAFStringConst_t requestingEndpoint, 304 STAFStringConst_t physicalInterfaceID, 305 STAFStringConst_t requestingUser, 306 STAFString_t *errorBuffer); 307 308 309 /*********************************************************************/ 310 /* STAFUtilConvertStringToUInt - Converts a number expressed as a */ 311 /* string to an unsigned integer within a specified range (that */ 312 /* defaults to range 0 to UINT_MAX if not specified) */ 313 /* */ 314 /* Accepts: (In) The string to be converted to an unsigned integer */ 315 /* (In) Option name string. Set to blank if the string */ 316 /* is not the value for an option. */ 317 /* This is used only in the error message. */ 318 /* (Out) The unsigned integer value */ 319 /* (Out) A pointer to an error string. */ 320 /* (In) The minimum value allowed (cannot be < 0) */ 321 /* The default is 0. */ 322 /* (Out) The maximum value allowed (cannot be > UINT_MAX */ 323 /* (e.g. 4294967295). The default is UINT_MAX. */ 324 /* */ 325 /* Returns: 0, if successful */ 326 /* 47 if unsuccessful (*errorBuffer will be set) */ 327 /*********************************************************************/ 328 STAFRC_t STAFUtilConvertStringToUInt(STAFStringConst_t theString, 329 STAFStringConst_t optionName, 330 unsigned int *theUInt, 331 STAFString_t *errorBuffer, 332 unsigned int minValue = 0, 333 unsigned int maxValue = UINT_MAX); 334 335 336 /*********************************************************************/ 337 /* STAFUtilConvertStringToUInt64 - Converts a number expressed as a */ 338 /* string to an unsigned integer within a specified range (that */ 339 /* defaults to range 0 to UINT64_MAX if not specified) */ 340 /* */ 341 /* Accepts: (In) The string to be converted to an unsigned integer */ 342 /* (In) Option name string. Set to blank if the string */ 343 /* is not the value for an option. */ 344 /* This is used only in the error message. */ 345 /* (Out) The unsigned integer (64-bit) value */ 346 /* (Out) A pointer to an error string. */ 347 /* (In) The minimum value allowed (cannot be < 0) */ 348 /* The default is 0. */ 349 /* (Out) The maximum value allowed (cannot be > UINT64_MAX */ 350 /* (e.g. 18446744073709551615). The default is */ 351 /* UINT64_MAX. */ 352 /* */ 353 /* Returns: 0, if successful */ 354 /* 47 if unsuccessful (*errorBuffer will be set) */ 355 /*********************************************************************/ 356 /* XXX: Commented out until get UINT64_MAX working on Solaris 357 STAFRC_t STAFUtilConvertStringToUInt64(STAFStringConst_t theString, 358 STAFStringConst_t optionName, 359 STAFUInt64_t *theUInt, 360 STAFString_t *errorBuffer, 361 STAFUInt64_t minValue = 0, 362 STAFUInt64_t maxValue = UINT64_MAX); 363 */ 364 365 366 /*********************************************************************/ 367 /* STAFUtilConvertDurationString - Converts the time duration */ 368 /* expressed as a string to a numeric value in milliseconds. */ 369 /* */ 370 /* Accepts: (In) The duration string */ 371 /* The duration string may be expressed in */ 372 /* milliseconds, seconds, minutes, hours, days, or */ 373 /* weeks. Its format is: */ 374 /* <Number>[<Type>] */ 375 /* where <Number> is an integer >= 0 and <Type>, if */ 376 /* specified, is one of the following: */ 377 /* s (for seconds), m (for minutes), h (for hours), */ 378 /* d (for days), or w (for weeks). For example: */ 379 /* - 100 specifies 100 milliseconds, */ 380 /* - 10s specifies 10 seconds, */ 381 /* - 5m specifies 5 minutes, */ 382 /* - 2h specifies 2 hours, */ 383 /* - 1d specifies 1 day, */ 384 /* - 1w specifies 1 week */ 385 /* (Out) The numeric duration value in milliseconds */ 386 /* (Out) A pointer to an error string */ 387 /* */ 388 /* Returns: 0, if successful */ 389 /* 47 if unsuccessful (*errorBuffer will be set) */ 390 /*********************************************************************/ 391 STAFRC_t STAFUtilConvertDurationString(STAFStringConst_t durationString, 392 unsigned int *duration, 393 STAFString_t *errorBuffer); 394 395 /*********************************************************************/ 396 /* STAFUtilConvertSizeString - Converts a size of a file expressed */ 397 /* as a string to a numeric value in bytes. */ 398 /* */ 399 /* Accepts: (In) The size string */ 400 /* The size string may be expressed in bytes, */ 401 /* kilobytes, or megabytes. Its format is: */ 402 /* <Number>[<Type>] */ 403 /* where <Number> is an integer >= 0 and <Type>, if */ 404 /* specified, is one of the following: */ 405 /* k (for kilobytes) or m (for megabytes). */ 406 /* For example: */ 407 /* - 100000 specifies 100,000 bytes, */ 408 /* - 500k specifies 500 kilobytes (or 512,000 bytes), */ 409 /* - 5m specifies 5 megabytes (or 5,242,880 bytes) */ 410 /* (Out) The numeric size value in bytes */ 411 /* (Out) A pointer to an error string */ 412 /* */ 413 /* Returns: 0, if successful */ 414 /* 47 if unsuccessful (*errorBuffer will be set) */ 415 /*********************************************************************/ 416 STAFRC_t STAFUtilConvertSizeString(STAFStringConst_t sizeString, 417 unsigned int *size, 418 STAFString_t *errorBuffer); 419 420 421 #ifdef __cplusplus 422 423 /***********************************************************************/ 424 /* VALIDATE_TRUST - Macro to verify that the actual trust level is */ 425 /* not less than the required trust level. This is what most of */ 426 /* the STAF C++ external services use to verify trust. */ 427 /* It assumes the service uses the following variable names: */ 428 /* - pInfo: contains the service request information */ 429 /***********************************************************************/ 430 #define VALIDATE_TRUST(requiredTrustLevel, service, request, localMachine)\ 431 STAFString_t stafUtilTrustErrorBuffer = 0;\ 432 STAFRC_t stafUtilTrustRC = STAFUtilValidateTrust(\ 433 pInfo->trustLevel, requiredTrustLevel, STAFString(service).getImpl(),\ 434 STAFString(request).getImpl(), localMachine.getImpl(),\ 435 pInfo->endpoint, pInfo->physicalInterfaceID, pInfo->user,\ 436 &stafUtilTrustErrorBuffer);\ 437 if (stafUtilTrustRC != kSTAFOk)\ 438 return STAFResultPtr(new STAFResult(kSTAFAccessDenied,\ 439 STAFString(stafUtilTrustErrorBuffer, STAFString::kShallow)),\ 440 STAFResultPtr::INIT); 441 442 443 /***********************************************************************/ 444 /* VALIDATE_TRUST2- Macro to verify that the actual trust level is */ 445 /* not less than the required trust level. This is just like */ 446 /* the VALIDATE_TRUST macro except it uses different names for */ 447 /* the variables it defines so that it can be run in the same */ 448 /* function as where you ran VALIDATE_TRUST. This can be useful */ 449 /* if you want to first check if a request has a trust level */ 450 /* but then you find that an option like FORCE was specified that */ 451 /* requires a higher trust level so you can then use this macro. */ 452 /* It assumes the service uses the following variable names: */ 453 /* - pInfo: contains the service request information */ 454 /***********************************************************************/ 455 #define VALIDATE_TRUST2(requiredTrustLevel, service, request, localMachine)\ 456 STAFString_t stafUtilTrustErrorBuffer = 0;\ 457 STAFRC_t stafUtilTrustRC = STAFUtilValidateTrust(\ 458 pInfo->trustLevel, requiredTrustLevel, STAFString(service).getImpl(),\ 459 STAFString(request).getImpl(), localMachine.getImpl(),\ 460 pInfo->endpoint, pInfo->physicalInterfaceID, pInfo->user,\ 461 &stafUtilTrustErrorBuffer);\ 462 if (stafUtilTrustRC != kSTAFOk)\ 463 return STAFResultPtr(new STAFResult(kSTAFAccessDenied,\ 464 STAFString(stafUtilTrustErrorBuffer, STAFString::kShallow)),\ 465 STAFResultPtr::INIT); 466 467 468 /***********************************************************************/ 469 /* VALIDATE_TRUST3 - Macro to verify that the actual trust level is */ 470 /* not less than the required trust level. This is what a STAF */ 471 /* C++ external service can use to verify trust if can't use the */ 472 /* pInfo variable (or a different named variable) to contain the */ 473 /* service request information. This macro can be used if */ 474 /* individual STAFStrings are used to contain the requesting */ 475 /* machine's trust level, endpoint, physicalInterfaceID, and/or */ 476 /* user values. */ 477 /***********************************************************************/ 478 #define VALIDATE_TRUST3(requiredTrustLevel, service, request, localMachine,\ 479 actualTrustLevel, endpoint, physicalInterfaceID, user)\ 480 STAFString_t stafUtilTrustErrorBuffer = 0;\ 481 STAFRC_t stafUtilTrustRC = STAFUtilValidateTrust(\ 482 actualTrustLevel, requiredTrustLevel, STAFString(service).getImpl(),\ 483 STAFString(request).getImpl(), localMachine.getImpl(),\ 484 STAFString(endpoint).getImpl(), STAFString(physicalInterfaceID).getImpl(),\ 485 STAFString(user).getImpl(), &stafUtilTrustErrorBuffer);\ 486 if (stafUtilTrustRC != kSTAFOk)\ 487 return STAFResultPtr(new STAFResult(kSTAFAccessDenied,\ 488 STAFString(stafUtilTrustErrorBuffer, STAFString::kShallow)),\ 489 STAFResultPtr::INIT); 490 491 492 /***********************************************************************/ 493 /* VALIDATE_TRUST4 - Macro to verify that the actual trust level is */ 494 /* not less than the required trust level. This is what a STAF */ 495 /* C++ external service can use to verify trust if it's not using */ 496 /* the standard name of pInfo to contain the service request */ 497 /* information. */ 498 /* - info: contains the service request information */ 499 /***********************************************************************/ 500 #define VALIDATE_TRUST4(requiredTrustLevel, service, request, localMachine,\ 501 info)\ 502 STAFString_t stafUtilTrustErrorBuffer = 0;\ 503 STAFRC_t stafUtilTrustRC = STAFUtilValidateTrust(\ 504 info->trustLevel, requiredTrustLevel, STAFString(service).getImpl(),\ 505 STAFString(request).getImpl(), localMachine.getImpl(),\ 506 info->endpoint, info->physicalInterfaceID, info->user,\ 507 &stafUtilTrustErrorBuffer);\ 508 if (stafUtilTrustRC != kSTAFOk)\ 509 return STAFResultPtr(new STAFResult(kSTAFAccessDenied,\ 510 STAFString(stafUtilTrustErrorBuffer, STAFString::kShallow)),\ 511 STAFResultPtr::INIT); 512 } 513 514 #endif 515 516 #endif 517