/*++ OPTIONS.HXX My option parsing system Copyright (C) 1997 Microsoft Corporation Created 01/13/1997 DavidCHR --*/ #ifndef INCLUDED_OPTIONS_H /* IMPORTANT! IMPORTANT! IMPORTANT! If you add option types, you MUST change this #define to point at your new type. The symbol used internally for certain assertions and at compile-time to find forgotten areas. IMPORTANT! IMPORTANT! IMPORTANT! */ #define HIGHEST_OPTION_SUPPORTED OPT_STOP_PARSING #define INCLUDED_OPTIONS_HXX #define OPTION_DEBUGGING_LEVEL 0x10000000 /* set your DebugFlag to this if you want OPTIONS_DEBUG */ #define OPTION_HELP_DEBUGGING_LEVEL 0x20000000 /* most people REALLY will not want to see this. */ typedef int (OPTFUNC)(int, char **); /* this is what's expected of OPT_FUNC*/ // OPT_FUNC2 and beyond will be defined in client.h /* NOTE that when defining this structure statically, you MUST use curly braces ({}), since the structure may change in size! */ typedef struct { PCHAR cmd; /* this is what we call from the command line eg "h" for -h or /h */ PVOID data; /* this is where we store the results of that, OR a function that can be called to store it (see below), OR null if this option is ignored or doesn't need storage */ ULONG flags; /* flags describing this option (see below for flags) */ PCHAR helpMsg; /* description of this option (example: "prints help screen" or "specifies a file to read") */ PVOID optData; /* if we specify OPT_ENVIRONMENT (for example), this is the environment variable we'll take the data from */ /* any/all remaining fields should be left alone */ BOOL Initialized; /* initially FALSE */ } optionStruct; /* use this macro to determine if you're at the end of the array or not-- it will change if the array termination conditions change. */ #define ARRAY_TERMINATED( poptions ) ( ( (poptions)->cmd == NULL ) && \ ( (poptions)->helpMsg == NULL ) && \ ( (poptions)->data == NULL ) && \ ( (poptions)->flags == 0 ) ) /* put this as the last element of your array. It will change if/when the termination conditions change */ #define TERMINATE_ARRAY { 0 } /* FLAGS these tell ParseOptions and PrintHelpMessage what the option is: */ /* These are mutually-exclusive, so they are set in a manner such that defining them together causes wierd results. */ #define OPT_HELP 0x01 /* print the help message */ #define OPT_STRING 0x02 /* option is a string */ #define OPT_INT 0x03 /* an integer (can be hex) */ #define OPT_LONG 0x04 /* a long integer */ #define OPT_BOOL 0x05 /* boolean */ #define OPT_FLOAT 0x06 /* a float */ #define OPT_FUNC 0x07 /* needs a function to parse and store */ #define OPT_DUMMY 0x08 /* don't store the result anywhere-- basically, a separator that appears in the help message */ #define OPT_CONTINUE 0x09 /* line is a continuation of the previous line-- useful for breaking really long descriptions into multiple short lines */ #define OPT_PAUSE 0x0A /* wait for the user to press RETURN */ #ifdef WINNT /* only available under Windows NT */ #define OPT_USTRING 0x0B /* UNICODE_STRING */ #define OPT_WSTRING 0x0C /* string of wide characters */ #ifdef UNICODE /* use OPT_TSTRING for TCHAR strings */ #define OPT_TSTRING OPT_WSTRING #else #define OPT_TSTRING OPT_STRING #endif #endif /* WINNT-- OPT_{U|W}STRING */ #define OPT_SUBOPTION 0x0D /* suboptions-- format is: [+|-|/](optname):(subopt), optname is the name of THIS OPTION (serves as a kind of "routing option". This gets converted to: [+|-|/](subopt) and is reparsed with the optionStruct that is given as data to this parameter within this structure. Nesting IS supported. Example follows. */ #if 0 /* EXAMPLE of OPT_SUBOPTION */ static optionStruct RoutedOptions[] = { /* note that each suboption must have its own OPT_HELP-- the help code will not browse the substructure. */ { "help", NULL, OPT_HELP, NULL }, { "myroute", &some_variable, OPT_BOOL, "set this to enable routing" }, { "nofoo", &defeat_foo, OPT_BOOL, "down with foo!" }, TERMINATE_ARRAY } static optionStruct myOptions[] = { { "help", NULL, OPT_HELP, NULL }, { "route", RoutedOptions, OPT_SUBOPTION, "Routing options" }, TERMINATE_ARRAY }; /* in this example, to get help with the routing options, one would specify -route:help to enable routing, the user would do: +route:myroute */ #endif #define OPT_ENUMERATED 0x0E /* Enumerated type. Depending on what the user enters for the field, we enter a user-defined value for the specified variable. We deliberately ignore the type of the values, the mapping-vector goes into the optData field, so we can't use OPT_ENVIRONMENT with this. and the array is currently terminated by a NULL UserField. Since this may change, use TERMINATE_ARRAY as above. the options are not case-sensitive, but if the user specifies an unknown value, an error will occur. */ typedef struct { PCHAR UserField; PVOID VariableField; PCHAR DescriptionField; /* if the description is left blank, the field will not be mentioned in help */ } optEnumStruct; #if 0 /* Example of OPT_ENUMERATED option */ typedef enum { UseUdpToConnect = 1, UseTcpToConnect = 2, } MyEnumType; optEnumStruct MyEnumerations[] = { { "udp", (PVOID) UseUdpToConnect, // casting will likely be needed if "Specifies a UDP connection" }, { "tcp", (PVOID) UseTcpToConnect, // your assignment is not a pointer "Specifies a TCP connection" }, TERMINATE_ARRAY }; MyEnumType MethodOfConnection; optionStruct MyOptions[] = { /* ... */ { "MyEnum", OPT_ENUMERATED, &MethodOfConnection, "example of an enumerated type-- -myEnum Tcp for tcp connections", MyEnumerations }, /* ... */ }; #endif #define OPT_FUNC2 0x0F /* enhanced function-- goes in the optData field, instead of the data field. See OPTFUNC2 above. */ #define OPT_STOP_PARSING 0x10 /* tells the parser to stop here. This is the equivalent of the ';' argument to -exec in unix's find command: find . -exec echo {} ; -something. the ; terminates parsing for the -exec option. However, parsing for find is unaffected. */ #define OPT_MUTEX_MASK 0xff /* mask for mutually exclusive options */ #define OPT_NONNULL 0x100 /* option cannot be zero or NULL after parsing-- not useful for BOOLs, DUMMYs, or HELP. This is a way of ensuring that an option DOES get specified. */ #define OPT_DEFAULT 0x200 /* option may be specified without the cmd-- multiple OPT_DEFAULTs may be specified. They get "filled in" in the order they exist in the options array. See the examples for more */ #define OPT_HIDDEN 0x400 /* option does not appear in help. I'm not sure if this ends up being useful or not, but I'm including it for completeness. */ #define OPT_ENVIRONMENT 0x800 /* use the optData field as an environment string from which to extract the default */ #define OPT_RECURSE 0x1000 /* define this if you want FindUnusedOptions to reparse the given substructure. Otherwise, it'll be ignored */ #define OPT_NOSWITCH 0x2000 /* do not print the leading [switches] line */ #define OPT_NOCOMMAND 0x4000 /* do not print the command name-- I don't know if you'd ever really want to do JUST this, but here it is.. */ #define OPT_NOALIGN 0x8000 /* don't even print alignment spaces. This will make your output REALLY UGLY if you're not careful */ #define OPT_NOSEPARATOR 0x10000 /* don't use a separator sequence (by default, I think it's ": ". Again, this is REALLY UGLY */ // should have named the below option "OPT_RAW", because that's what it is. #define OPT_NOHEADER ( OPT_NOSWITCH | OPT_NOCOMMAND | OPT_NOALIGN | \ OPT_NOSEPARATOR ) #define OPT_ENUM_IS_MASK 0x20000 /* force enumerated types to also accept enums of the form XXX | YYY | ZZZ */ #if 0 /* EXAMPLE */ optionStruct my_options[] = { { "default1", &myDefaultInt, OPT_INT | OPT_DEFAULT, "an int value"}, {"default2", &myOtherInteger, OPT_INT | OPT_DEFAULT, "another int" }, {"required", &myRequiredString, OPT_STRING | OPT_NONNULL, "a must have" }, TERMINATE_ARRAY }; /*++ in the example above, if your app was named "foo", the following would be equivalent: foo -default1 0 -default2 13 -required bleah foo 0 13 -required bleah foo 0 -default2 13 -required bleah foo -required bleah -default2 13 0 ...and failing to specify "-required" would always result in an error if myRequiredString is NULL to begin with. Note that the options must be in order. If you mix types (if default2 were a string, and you run "foo bleah 0 for example"), the results are undefined. --*/ #endif /* ParseOptionsEx: initializes the option structure, which is a sentinally-terminated vector of optionStructs. argc, argv: arguments to main() (see K&R) pOptionStructure: vector of optionStructs, terminated with TERMINATE_ARRAY optionFlags: optional flags to control api behavior ppReturnedMemory: returned handle to a list of memory to be freed before program exit. Use CleanupOptionDataEx to free it. new_arg[c,v]: if nonnull, a new argc and argv are returned here. if all the options were used up, argc = 0 and argv is NULL. Note that it is safe to provide pointers to the original argv/argc if so desired. The function's behavior is complex: the function will always return FALSE on any critical error (unable to allocate memory, or invalid argument). On WINNT, Last Error will be set to the appropriate error. if new_argc AND new_argv are specified, ParseOptionsEx will always return TRUE unless help was called, and the two parameters will be updated to reflect new values. otherwise: ParseOptionsEx will return TRUE if it was able to recognize ALL args on the command line given. It will return FALSE if any of the options were unknown. This will probably be what most people want. */ BOOL ParseOptionsEx( int argc, char **argv, optionStruct *pOptionStructure, ULONG optionFlags, void **ppReturnedMemory, int *new_argc, // optional char ***new_argv ); // optional /* These are the flags that ParseOptionsEx accepts: */ #define OPT_FLAG_TERMINATE 0x01 // call exit() on error // these next two are not yet fully supported and are mutually exclusive. #define OPT_FLAG_SKIP_UNKNOWNS 0x02 // skip unknown parameters #define OPT_FLAG_REASSEMBLE 0x04 /* assemble new argv/argc with unknown parameters in it-- only valid if new_argc and new_argv are specified this is useless with SKIP_UNKNOWNS. */ #define OPT_FLAG_MEMORYLIST_OK 0x08 /* this means ParseOptionsEx should not return a new memory list-- it should use the provided one. */ #define OPT_FLAG_INTERNAL_RESERVED 0xf0 /* flags 0x80, 0x40, 0x20 and 0x10 are reserved for internal use */ // if you add flags, update this #define. #define HIGHEST_OPT_FLAG OPT_FLAG_INTERNAL_RESERVED /* CleanupOptionDataEx: frees data in the given list, which may be empty ( but not NULL ) */ VOID CleanupOptionDataEx( PVOID pMemoryListToFree ); /* UnparseOptions: creates an argc/argv-like structure from a flat command. This is needed particularly for unix clients, although nt clients can use it without pulling in SHELL32.LIB. :-) */ BOOL UnparseOptions( PCHAR flatCommand, int *pargc, PCHAR *pargv[] ); #ifndef OPTIONS_NO_BACKWARD_COMPATIBILITY /* ParseOptions initializes the option structure-- note that the vector (optionStruct *) must be terminated with a sentinal value. This function is obsolete and is included for compatibility with older code. Call ParseOptionsEx instead. */ int ParseOptions( /* IN */ int argc, /* IN */ char **argv, /* IN */ /* OUT */optionStruct *options ); /* call cleanupOptionData at the end of your program. This will clear all memory used by the option parsing and returning system. */ VOID CleanupOptionData( VOID ); #endif #define ISSWITCH( ch /*character*/ ) ( (ch=='-') || (ch=='+') || (ch=='/') ) #endif // file inclusion check.