HRESULTs
Many, if not most of the GI calls in SkyGI return HRESULTs. What is an HRESULT exactly? It couldn't be more simple. It's just a typedef'd long. HRESULTs just make code a little bit easier to understand. Instead of return 0 on success and 1 on failure, HRESULT returning functions return S_OK and S_FALSE respectively.
Let's look at possible HRESULTs:
Success Codes: These will be returned when a function succeeds, or actually, when the function doesn't go down in flames. Note the 'S' prefix means 'success.' S_OK: No error. Function call succeeded. S_FALSE: No error, but the call failed. Error Codes: These will be returned when the function call does go down in flames. Some have names that make their meanings completely obvious. Others... well, no one but Robert himself know what they mean. Note, the 'E' prefix means 'error.' E_UNEXPECTED E_NOTIMPL E_ACCESSDENIED E_HANDLE E_OUTOFMEMORY E_INVALIDARG E_NOINTERFACE E_POINTER E_ABORT E_FAIL E_FAIL_DEBUG_TXT E_PIPE E_AGAIN Disk and filesystem Error Codes: E_DISK_SPACE E_DISK_READ_ERROR E_DISK_WRITE_ERROR E_IO_ERROR E_FILE_NOT_FOUND E_FILE_TOO_MANY_OPEN_FILES E_FILE_NO_DIRECTORY E_FILE_IS_DIRECTORY E_FILE_EOF E_WOULD_BLOCK E_FILE_IS_PIPE E_PIPE_ERROR E_TIMEOUT E_FILE_EXISTS Network Error Codes: E_NETIF_OPEN E_NETIF_CLOSE E_LIBNET_DEVICE_UNKNOWN E_LIBNET_DHCP_FAILED E_LIBNET_PPP_OPEN_SERIAL E_NETIF_BUFFER E_NO_ROUTE E_BUSY E_INTERRUPTED ISS Error Codes: E_ISS_BUSY E_ISS_UNKNOWN_FILE_FORMAT E_ISS_NOT_SUPPORTED E_ISS_END_OF_FILE
If these HRESULTs are not enough for your program, Robert was even so kind as to include a "MAKE_HRESULT" macro. The macro is as follows:
#define MAKE_HRESULT(sev, fac, code) \
((HRESULT) (((unsigned long)(sev)<<31) | ((unsigned long)(fac)<<16) | ((unsigned long)(code))) )
The parameters' have the following meanings:
sev - Severity code
fac - The facility code
code - The facility's status code
All HRESULTs' severity codes are '800' so I'd suggest keeping with tradition and making your custom HRESULTs also begin with an '800.' The facility codes determine what type of function returned the error. Some Predefined HRESULTs groups have the following severity codes:
Success: 000 Disk: 800 Filesystem: 900 ISS: 200
These facility codes are not enforced. Robert doesn't seem to keep up with them himself. Network HRESULTs many times have the same facility number as disk errors. Not to worry though, these numbers are completely arbitrary.
Finally, the facility's status code is whatever you'd like it to be. One word of advice when creating custom HRESULTs is to make sure your HRESULT is unique so that when you think your function is returning S_OK, your program doesn't interpret it as E_COMPUTER_ON_FIRE.