stafutil.h

Software Testing Automation Framework (STAF)的开发代码

/*****************************************************************************/
/* Software Testing Automation Framework (STAF)                              */
/* (C) Copyright IBM Corp. 2001                                              */
/*                                                                           */
/* This software is licensed under the Common Public License (CPL) V1.0.     */
/*****************************************************************************/

#ifndef STAF_Util
#define STAF_Util

#include "STAF.h"
#include "STAFString.h"
#include "STAFProcess.h"
#include <stdarg.h>

#ifdef __cplusplus
extern "C"
{
#endif

/* Define min and max macros.  We've had conflicts using raw min() and max() */

#define STAF_MIN(a,b) ((a) <= (b) ? (a) : (b))
#define STAF_MAX(a,b) ((a) >= (b) ? (a) : (b))

/* Defines a structure to receive configuration information */
struct STAFConfigInfo
{
    STAFStringConst_t bootDrive;
    STAFStringConst_t osName;
    STAFStringConst_t osMajorVersion;
    STAFStringConst_t osMinorVersion;
    STAFStringConst_t osRevision;
    unsigned long physicalMemory;
    STAFStringConst_t exePath;
    STAFStringConst_t lineSeparator;
    STAFStringConst_t fileSeparator;
    STAFStringConst_t pathSeparator;
    STAFStringConst_t commandSeparator;
    STAFProcessStopMethod_t defaultProcessStopMethod;
    unsigned int envVarCaseSensitive; /* 0=CaseInsensitive; 1=CaseSensitive */
};


/*********************************************************************/
/* STAFUtilGetConfigInfo - Retrieves OS configuration information    */
/*                                                                   */
/* Accepts: (Out) A pointer to a STAFConfigInfo structure            */
/*          (Out) A pointer to an error string                       */
/*          (Out) A pointer to an operating system return code       */
/*                                                                   */
/* Returns:  0, if successful                                        */
/*          >0, if unsuccessful (*errorBuffer and *osRC will be set) */
/*********************************************************************/
unsigned int STAFUtilGetConfigInfo(struct STAFConfigInfo *configInfo,
                                   STAFString_t *errorBuffer,
                                   unsigned int *osRC);


/*********************************************************************/
/* STAFUtilGetCurrentProcessCodePage - Obtains a string representing */
/*                                     the current process' code     */
/*                                     page                          */
/*                                                                   */
/* Accepts: (In)  A pointer to the buffer to hold the code page      */
/*                string (this should be large enough to hold the    */
/*                largest codepage string for the operating system;  */
/*                typically 128 bytes should be sufficient)          */
/*                                                                   */
/* Returns:  The pointer passed in                                   */
/*********************************************************************/
char *STAFUtilGetCurrentProcessCodePage(char *buffer);


/*********************************************************************/
/* STAFUtilGetPID - Returns the effective Process ID (PID)           */
/*                                                                   */
/* Accepts: Nothing                                                  */
/*                                                                   */
/* Returns:  The Process' ID                                         */
/*                                                                   */
/* Notes  :  1) This routine should be used instead of getpid(), as  */
/*              getpid() behaves strangely in a multi-threaded       */
/*              environment on Linux                                 */
/*********************************************************************/
STAFProcessID_t STAFUtilGetPID();


/*********************************************************************/
/* STAFUtilGetSystemMemory - Obtains a piece of system memory        */
/*                                                                   */
/* Accepts: (In)  The size of the memory needed                      */
/*          (Out) Pointer to an operating system return code         */
/*                                                                   */
/* Returns:  0, if unsuccessful (*osRC will be set)                  */
/*          >0, if successful (this is the address of the memory)    */
/*********************************************************************/
void *STAFUtilGetSystemMemory(unsigned long size, unsigned int *osRC);


/*********************************************************************/
/* STAFUtilFreeSystemMemory - Frees a piece of system memory         */
/*                                                                   */
/* Accepts: (In)  The pointer to the system memory to free           */
/*                                                                   */
/* Returns:  Nothing                                                 */
/*********************************************************************/
void STAFUtilFreeSystemMemory(void *);


/*********************************************************************/
/* STAFUtilSwapUInt - Byte reverses an unsigned int.  In other       */
/*                    words, it converts from little-endian or       */
/*                    visa-versa.                                    */
/*                                                                   */
/* Accepts: (In)  The unsigned int to byte reverse                   */
/*                                                                   */
/* Returns:  The byte-reversed unsigned int                          */
/*********************************************************************/
unsigned int STAFUtilSwapUInt(unsigned int theUInt);


/*********************************************************************/
/* STAFUtilConvertNativeUIntToLE - Converts an unsigned in the       */
/*                                 platform's native format to       */
/*                                 little-endian format              */
/*                                                                   */
/* Accepts: (In)  The unsigned int to convert to little-endian       */
/*                                                                   */
/* Returns:  The little-endian version of the unsigned int           */
/*********************************************************************/
unsigned int STAFUtilConvertNativeUIntToLE(unsigned int theUInt);


/*********************************************************************/
/* STAFUtilConvertLEUIntToNative - Converts an unsigned in           */
/*                                 little-endian format to the       */
/*                                 platform's native format          */
/*                                                                   */
/* Accepts: (In)  The unsigned int to convert to little-endian       */
/*                                                                   */
/* Returns:  The little-endian version of the unsigned int           */
/*********************************************************************/
unsigned int STAFUtilConvertLEUIntToNative(unsigned int theUInt);


/*********************************************************************/
/* STAFUtilIsValidSocket - Determines if a socket descriptor,        */
/*                         received from socket() or accept() is     */
/*                         valid                                     */
/*                                                                   */
/* Accepts: (In)  The socket to check                                */
/*                                                                   */
/* Returns:  0, if the socket is invalid                             */
/*          >0, if the socket is valid                               */
/*********************************************************************/
unsigned int STAFUtilIsValidSocket(STAFSocket_t theSocket);


/*********************************************************************/
/* STAFUtilGetNonInheritableSocket - Provides a new socket that is   */
/*   a identical to the old socket except the new socket cannot be   */
/*   inherited by new processes.                                     */
/*                                                                   */
/* Accepts: (In)  The socket to duplicate                            */
/*          (Out) The new socket (with inheritHandle set to FALSE)   */
/*          (Out) A pointer to an operating system return code       */
/*                                                                   */
/* Returns:  0, if successful                                        */
/*          >0, if unsuccessful (*osRC will be set)                  */
/*********************************************************************/
unsigned int STAFUtilGetNonInheritableSocket(STAFSocket_t oldSocket,
                                             STAFSocket_t *newSocket,
                                             unsigned int *osRC);


/*********************************************************************/
/* STAFUtilFormatString - Generates a string based on a format       */
/*                        string, ala printf().  This is generally   */
/*                        used to format STAF request strings.       */
/*                                                                   */
/* Accepts: (In)  The format string                                  */
/*          (Out) A pointer to the output string                     */
/*          (In)  All data indicated in the format string            */
/*                                                                   */
/* Returns:  Standard return codes                                   */
/*                                                                   */
/* Notes  :  1) The caller is responsible for destructing the        */
/*              output string                                        */
/*********************************************************************/
/* Valid format string specifiers:                                   */
/*                                                                   */
/* %d - an unsigned integer                                          */
/* %s - a STAFString_t                                               */
/* %C - a STAFString_t which will be formatted in colon-length-colon */
/*      delimited format                                             */
/* %% - a percent sign                                               */
/*                                                                   */
/* Any other %<char> is simply ignored (and not copied)              */
/*********************************************************************/
unsigned int STAFUtilFormatString(STAFStringConst_t formatString,