#include <ex.h>
Public Methods | |
| ex () | |
| The default ctor does precisely nothing. More... | |
| ex ( const ex &e ) | |
| The copy ctor initialises *this to a copy of the exception e. More... | |
| ex ( const TCHAR *newFile, int newLine, Errcode newErr, const TCHAR *newMsg, DWORD newErrWin32 = 0, DWORD newData = 0 ) | |
| initialises an ex object from bits and pieces supplied by you. More... | |
| virtual | ~ex () |
| The dtor, well, duh. Supply your own comment here ... More... | |
| virtual void | shoo () |
| basically executes a delete this, avoiding problems with multiple copies of the runtime library. More... | |
| const ex& | operator= ( const ex &e ) |
| Assignment operator. More... | |
| void | AddHop ( const TCHAR *newFile, int newLine, const TCHAR *newMsg ) |
| adds an entry to the hop list. More... | |
| void | SetErr ( Errcode newErr ) |
| sets the object's error code. More... | |
| Errcode | GetErr () const |
| returns the object's error code. More... | |
| const TCHAR* | GetErrString () const |
| retrieves the string name of the object's error code. More... | |
| void | SetErrWin32 ( DWORD newErrWin32 ) |
| sets the Win32 error code that, presumably, is the reason for the exception being thrown. More... | |
| DWORD | GetErrWin32 () const |
| gets the Win32 error code that, presumably, is the reason for the exception being thrown. More... | |
| void | SetData ( DWORD newData ) |
| sets optional exception data. More... | |
| DWORD | GetData () const |
| retrieves optional exception data. More... | |
| size_t | GetHopCount () const |
| gets number of entries in the hop list. More... | |
| Hop& | operator[] ( size_t index ) |
| gets a non-const reference to a hop entry. More... | |
| const Hop& | operator[] ( size_t index ) const |
| gets a const reference to a hop entry. More... | |
| fkstr | GetWin32Desc () const |
| return the string for errWin32. More... | |
Private Types | |
| typedef std::vector<Hop> | HopList |
| the list of catch handlers that were traversed. More... | |
Private Attributes | |
| fksec::ex::HopList | hops |
| the list of catch handlers having seen the exception. More... | |
| fksec::Errcode | err |
| the error code. Meanings are listed in the documentation for the fksec::Errcode enumeration. More... | |
| DWORD | errWin32 |
| the Win32 error code that caused the exception, if any; else 0. More... | |
| DWORD | data |
| additional data, if any; else 0. More... | |
Static Private Attributes | |
| const TCHAR* | errStrings [] |
| name strings for the Errcode enumeration values. More... | |
| const int | numErrStrings = sizeof errStrings / sizeof errStrings[0] |
| the count of string pointers in the errStrings[] array. More... | |
Friends | |
| fkostream& | operator<< ( fkostream &o, const ex& e ) |
| dumps this exception to a stream. More... | |
The fksec classes use C++ exceptions to report errors, with a very few functions reporting success or failure through normal return values (these are mostly of the "IsValid()" type, which one would expect to return false instead of going bang.)
An exception object records at least one of the error codes defined in the ex::Errcode enumeration, an accompanying text message, and a list of source-file/line-number/error-message combinations, starting with the source line that threw the exception. Additionally, the exception object may contain a Win32 error code, and a DWORD of additional data, which is used to communicate minimum required buffer sizes and the like.
You should expect every method of every class to throw an exception at you (except where explicitly noted otherwise in a method's discussion below). That means that all your uses of fksec classes should be wrapped in try … catch blocks:
try { sid.StoreSid( thatBuffer, bufferSize ); }
catch ( ex *e )
{
if ( e->GetErr() == something )
{
// handle this exception
e->shoo(); // and delete it
}
else
{
// clean up here
throw;
}
}In general you will not want to wrap every single method call into its own exception handler; fksec does that internally only in order to pinpoint more precisely where an error occurred or was caught and re-thrown.
Note that you are expected to delete the fksec exceptions you catch, unless you re-throw them. Due to the possible conflict between the memory allocation structures of multiple modules linked with a static runtime library, the exception class provides a method to do this safely - see shoo() below.
As mentioned above, the error code, accessible through GetErr() and GetErrString(), is the most important part - it tells you what went wrong. If the error was caused by the failure of a Win32 API function, GetErrWin32() will return a non-zero value, the result of GetLastError() at the point of failure. If the error was caused by passing too small a buffer, GetData() tells you how large the buffer must be; this affects mainly the StoreSid(), StoreAce(), StoreAcl(), StoreSd() functions which expect a caller-supplied buffer.
Finally, the list of source lines where the exception was thrown or re-thrown on its way to you contains messages explaining what the code was trying to do when the error was detected.
Note that none of this is intended for the user's eyes; handling errors is your job. Also note carefully that NT exceptions - access violations due to invalid pointers passed in, for example - are not caught or handled by the code. This is on the to-do list, though.
Definition at line 255 of file ex.h.
|
|
the list of catch handlers that were traversed.
|
|
|
The default ctor does precisely nothing.
|
|
|
The copy ctor initialises *this to a copy of the exception e.
Definition at line 34 of file ex.cpp. 00035 {
00036 hops = e.hops;
00037 err = e.err;
00038 errWin32 = e.errWin32;
00039 data = e.data;
00040 }
|
|
|
initialises an ex object from bits and pieces supplied by you. ex.h contains the NEWEX and NEWEX32 macros, which you might find useful if you extend the classes and wish to stick with my exceptions.
Definition at line 18 of file ex.cpp. 00020 {
00021 Hop h;
00022 h.file = newFile;
00023 h.line = newLine;
00024 h.msg = newMsg;
00025 hops.push_back( h );
00026
00027 if ( newErr >= errNone && newErr < errMaxError )
00028 err = newErr;
00029 errWin32 = newErrWin32;
00030 data = newData;
00031 }
|
|
|
The dtor, well, duh. Supply your own comment here ...
Definition at line 297 of file ex.h. 00297 { }
|
|
|
adds an entry to the hop list. AddHop() is the method that adds an entry to the exception's history. (The first entry is usually made during construction of the exception object.) For uses, see any of the other classes' source files.
Definition at line 70 of file ex.cpp. 00071 {
00072 Hop h;
00073 h.file = newFile;
00074 h.line = newLine;
00075 h.msg = newMsg;
00076 hops.push_back( h );
00077 }
|
|
|
retrieves optional exception data. Some exceptions communicate a DWORD (say, the minimum size of a buffer that was too small) to the user. This method retrieves that value. If the return is 0, the value was not set.
Definition at line 381 of file ex.h. 00381 { return data; }
|
|
|
returns the object's error code.
Definition at line 341 of file ex.h. 00341 { return err; }
|
|
|
retrieves the string name of the object's error code. Note that this is just the name of the Errcode constant, not something you can show to a user.
Definition at line 87 of file ex.cpp. 00088 {
00089 if ( err >= numErrStrings )
00090 return _T( "-unknown-" );
00091
00092 return errStrings[err];
00093 }
|
|
|
gets the Win32 error code that, presumably, is the reason for the exception being thrown.
Definition at line 363 of file ex.h. 00363 { return errWin32; }
|
|
|
gets number of entries in the hop list. The hop list has one entry for each catch handler that passed the exception on (by re-throwing it), plus one for the initial throw, assuming that every intermediate handler bothered to add itself to the hop list. This function retrieves the number of entries in this list.
Definition at line 392 of file ex.h. 00392 { return hops.size(); }
|
|
|
return the string for errWin32. GetWin32Desc() returns the string corresponding to the Win32 error code of *this.
Definition at line 121 of file ex.cpp. 00122 {
00123 LPVOID lpMsgBuf = 0;
00124
00125 if ( 0 == FormatMessage( FORMAT_MESSAGE_ALLOCATE_BUFFER |
00126 FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS,
00127 NULL, errWin32, MAKELANGID( LANG_NEUTRAL, SUBLANG_DEFAULT ),
00128 (LPTSTR) &lpMsgBuf, 0, NULL ) )
00129 return fkstr( _T( "Oops! FormatMessage() failed" ) );
00130
00131 fkstr desc = (TCHAR *)lpMsgBuf;
00132 LocalFree(lpMsgBuf);
00133 return desc;
00134 }
|
|
|
sets optional exception data. Some exceptions communicate a DWORD (say, the minimum size of a buffer that was too small) to the user. This is how.
Definition at line 371 of file ex.h. 00371 { data = newData; }
|
|
|
sets the object's error code. The operation fails silently if the error code is out-of-range.
Definition at line 80 of file ex.cpp. 00081 {
00082 if ( newErr >= errNone && newErr < errMaxError )
00083 err = newErr;
00084 }
|
|
|
sets the Win32 error code that, presumably, is the reason for the exception being thrown.
Definition at line 357 of file ex.h. 00357 { errWin32 = newErrWin32; }
|
|
|
Assignment operator. I do prefer to have explicit assignment operators (or private, unimplemented, ones), if only to prevent the compiler from doing what it thinks best.
Definition at line 53 of file ex.cpp. 00054 {
00055 if ( this != &e )
00056 {
00057 hops = e.hops;
00058 err = e.err;
00059 errWin32 = e.errWin32;
00060 data = e.data;
00061 }
00062
00063 return *this;
00064 }
|
|
|
gets a const reference to a hop entry. Hop entries are numbered 0 through GetHopCount() - 1. The structure of a hop entry itself is defined in ex.h.
Definition at line 96 of file ex.cpp. 00097 {
00098 if ( index >= hops.size() )
00099 throw NEWEX( errBadHopIndex, "Out-of-range index when accessing exception hops" );
00100
00101 return hops[index];
00102 }
|
|
|
gets a non-const reference to a hop entry. Hop entries are numbered 0 through GetHopCount() - 1. The structure of a hop entry itself is defined in ex.h.
Definition at line 105 of file ex.cpp. 00106 {
00107 if ( index >= hops.size() )
00108 throw NEWEX( errBadHopIndex, "Out-of-range index when accessing exception hops" );
00109
00110 return hops[index];
00111 }
|
|
|
basically executes a delete this, avoiding problems with multiple copies of the runtime library.
Definition at line 44 of file ex.cpp. 00045 {
00046 delete this;
00047 }
|
|
|
dumps this exception to a stream. An fkostream is a synonym for a std::ostream or a std::wostream, depending on the Unicode settings. operator<< writes a human-readable representation of the exception to such a stream, useful for diagnostics. Note that the output takes multiple lines and ends with a newline.
|
|
|
additional data, if any; else 0.
|
|
|
the error code. Meanings are listed in the documentation for the fksec::Errcode enumeration.
|
|
|
Initializer: {
_T( "errNone" ),
_T( "errBadHopIndex" ),
_T( "errTooManySubAuths" ),
_T( "errInvalidSid" ),
_T( "errInvalidSubAuthIndex" ),
_T( "errNoMemory" ),
_T( "errBufferTooSmall" ),
_T( "errInvalidAce" ),
_T( "errInvalidAcl" ),
_T( "errInvalidAceIndex" ),
_T( "errStubbornPriv" ),
_T( "errQueryToken" ),
_T( "errDupTokenHandle" ),
_T( "errOpenToken" ),
_T( "errCloseToken" ),
_T( "errInvalidPriv" ),
_T( "errUnreadableSD" ),
_T( "errUnwritableSD" ),
_T( "errInvalidSD" ),
_T( "errNoPrefixSid" ),
_T( "errInvalidHandle" ),
_T( "errAdjustToken" ),
_T( "errNetApi32" ),
_T( "errMaxError" )
}
|
|
|
the Win32 error code that caused the exception, if any; else 0.
|
|
|
the list of catch handlers having seen the exception. As the exception bubbles its way up the call stack, catch handlers add their comments to this list.
|
|
|
the count of string pointers in the errStrings[] array.
|
1.2.2 written by Dimitri van Heesch,
© 1997-2000