Сообщений 26    Оценка 1440 [+3/-0]         Оценить

RSDN handle library

Набор классов-оберток для объектов ядра

Авторы: Павел Блудов
Александр Корсуков
Владислав Чистяков
The RSDN Group

Опубликовано: 09.06.2004
Исправлено: 05.01.2007
Версия текста: 2.2

Исходный текст (24kb)

Введение

Вашему вниманию предлагается небольшая библиотека классов, реализующих обертки (wrappers) над хендлами (handles) таких объектов, как файлы, объекты синхронизации, процессы и нити (threads).

Идея такой библиотеки не нова, на данный момент существует несколько подобных реализаций (например ATL::CHandle, ATL::CEvent и другие из ATL 7.0). Достоинствами предлагаемой библиотеки является ее полная независимость от других библиотек, ее можно использовать в MFC, ATL проектах и просто проектах, написанных на "чистом" API. Библиотека может использоваться в уникодных (Unicode), ANSI и смешанных проектах. Кроме того, в библиотеку включены несколько вспомогательных функций, упрощающих работу с API.

У каждого класса есть пара: класс, с таким же именем, но с суффиксом Handle. Например CProcessHandle. От парного класса, handle-класс отличается тем, что не закрывает свой хеднл в деструкторе. Их удобно использовать в качестве входных параметров процедур:

void DoSmth(RSDN::CProcessHandle h)
{
	h.SetAffinityMask(1);
}

RSDN::CProcess hProcess(dwProcessId, PROCESS_ALL_ACCESS);
if (hProcess)
	DoSmth(hProcess);

Если вместо RSDN::CProcessHandle использовать RSDN::CProcess в качестве входного параметра, произойдет неявный вызов ::DuplicateHandle() перед вызовом процедуры и ::CloseHandle() при выходе из нее.

Все классы содержат одну переменную m_h, в которой находится хендл, ассоциированный с данным объектом. Таким образом, выполняется равенство

sizeof(HANDLE) == sizeof(CHandle) == sizeof(CEvent) == sizeof(CEventHandle); // и т.д.

Порядок следования аргументов в методах классов, вызывающих функции API совпадает с порядком в вызываемых функциях. Кроме тех случаев, если в начале идут параметры практически никогда не используемые. Например, параметр LPSECURITY_ATTRIBUTES у метода RSDN::CEvent::Create() идет последним и равен по умолчанию нулю.

Еще одно важное замечание: про конструкторы. Если конструктор вызывает какой-либо метод, например Open() или Create(), а тот не отрабатывает успешно, то код ошибки может быть утерян. Если код ошибки важен, лучше явно вызвать соответствующий метод:

RSDN::CProcess hProcess;
if (FALSE == hProcess.Open(dwProcessId, PROCESS_ALL_ACCESS))
	ReportErrorToUser(::GetLastError());

Краткое описание

Далее приведены списки методов классов, в левой колонке название метода, в правой описание или просто функции, вызываемые из этого метода.

CHandle

Базовый класс. Абстрактная обертка над любым хендлом, нуждающемся в вызове ::CloseHandle().

Самое узкое место этого класса – его конструкторы. Дело в том, что будучи нормальным C++ классом, наш RSDN::CHandle должен иметь конструктор копирования, позволяющий использовать одни HANDLE-объект несколькими RSDN::CHandle-объектами. Но с таком случае, только деструктор последнего RSDN::CHandle-объекта должен закрыть единственный HANDLE-объект. Т.е. необходимо реализовать механизм подсчета ссылок. В данном классе эта тяжкая работа поручена операционной системе; используется API ::DuplicateHandle(). Это не самое легковесное решение, и его использование сведено к минимуму. Конструктор копирования использует эту функцию, а обычный конструктор и переопределенный оператор присваивания нет.

RSDN::CHandle hRead, hWrite;
// Duplicate handle не используется
BOOL b = ::CreatePipe(&hRead, &hWrite, NULL, 0);

// Duplicate handle не используется
RSDN::CHandle hEvent = ::CreateEvent(NULL, false, false, NULL);

// Вызывается Duplicate handle
RSDN::CHandle hDup = hRead;

// ОШИБКА: НЕ ВЫЗЫВАЕТСЯ Duplicate handle,
// после уничтожения обного из объектов
// у второго остается недействительный HANDLE
RSDN::CHandle hDup = hRead.m_h;

Обратите внимание, что operator=(const CHandle&) и конструктор копирования CHandle(const CHandle&) неявно вызывают метод DuplicateFrom(). Избегайте использования этих методов, заменяя их на явный вызов DuplicateFrom() или Attach(other.Detach()):

RSDN::CHandle hPrev;
for(/*...*/)
{
    RSDN::CHandle hNext = ::CreateFile(/*...*/);
    // ...
    hPrev = hNext;
}

В этом примере все время происходит вызов функций Duplicate/Close, которых можно избежать, изменив код следующим образом:

RSDN::CHandle hPrev;
for(/*...*/)
{
    RSDN::CHandle hNext = ::CreateFile(/*...*/);
    // ...
    hPrev.Attach(hNext.Detach());
}

Эти методы были добавлены для поддержки вот такого (довольно экзотического) кода:

__STD::vector<CAdapt<RSDN::CHandle> > m_vector;

for(int i = 0; i < 10; i++)
    m_vector.push_back(::CreateThread(/*...*/));

Который, тем не менее, можно (и нужно) переделать в что-то вроде:

__STD::vector<CAdapt<RSDN::CHandle> > m_vector;
m_vector.resize(10);

for(int i = 0; i < 10; i++)
    m_vector[i].m_T = ::CreateThread(/*...*/);

Далее следует полный список методов.

CFile

CConsole

CCompletionPort

CFileMapping

CNamedPipe

CMailslot

CDevice

CCommFile

CTape

CEvent

CMutex

CSemaphore

CWaitableTimer

CMemoryResourceNotification

CProcess

CThread

CJobObject

CToken

CToolhelpSnapshot

CModule

Вспомогательные функции (chandle.h)

static DWORD WaitForSingleObjectWithMessageLoop
	( HANDLE hEvent
	, DWORD nTimeout = INFINITE
	, BOOL bProcessAPC = FALSE
	);

Ожидает события hEvent не долее чем nTimeout миллисекунд с обработкой сообщений.

При bProcessAPC = TRUE также обрабатываются вызовы асинхронных процедур (APC).

Если во время ожидания события из очереди было изъято сообщение WM_QUIT (что, как правило, говорит об архитектурной ошибке), то на выходе из процедуры это сообщение возвращается обратно в очередь. Если такое поведение не требуется, можно определить макрос RSDN_CHANDLE_NO_WMQUITCHECK перед включением файла <rsdn/chandle.h>.

inline bool IsValidHandle
	( HANDLE h
	);

Просто проверяет значение h на неравенство нулю. Кроме того, если определен макрос _DEBUG, то "правильность" хендла проверяется через вызов API ::GetHandleInformation().

inline BOOL DuplicateHandle
	( HANDLE hSource
	, BOOL bInherit
	, LPHANDLE lpDest
	);

Дублирует хендл для использования в текущем процессе. Это облегченная версия стандартного API ::DuplicateHandle().

Вспомогательные функции (cproc.h)

inline bool IsValidProcess
	( HANDLE hProcess
	);

Версия IsValidHandle(), специально предназначенная для проверки хендлов процессов.

inline bool IsValidThread
	( HANDLE hThread
	);

Версия RSDN::IsValidHandle(), специально предназначенная для проверки хендлов нитей.

inline BOOL CreateProcess
	( LPCTSTR lpApplicationName
	, LPTSTR lpCommandLine
	, LPSECURITY_ATTRIBUTES lpProcessAttributes
	, LPSECURITY_ATTRIBUTES lpThreadAttributes
	, BOOL bInheritHandles
	, DWORD nCreationFlags
	, LPVOID lpEnvironment
	, LPCTSTR lpCurrentDirectory
	, LPSTARTUPINFO lpStartupInfo
	, LPHANDLE lphProcess = NULL
	, LPHANDLE lphThread = NULL
	, LPDWORD lpnProcessId = NULL
	, LPDWORD lpnThreadId = NULL
	);

Аналог стандартного ::CreateProcess(), но возвращающая хендлы и идентификаторы не одной структурой, а четырьмя отдельными параметрами.

Предназначена для облегчения конструкций типа

RSDN::CProcess hProcess;
RSDN::CThread hThread;
BOOL bSuccess = RSDN::CreateProcess(NULL, _T("Program.exe"), NULL, NULL, FALSE, 0, NULL, NULL, &si, &hProcess, &hThread);

Используется в методе RSDN::CProcess::Create();

inline BOOL CreateProcess
	( LPCTSTR lpApplicationName
	, LPTSTR lpCommandLine
	, DWORD nCreationFlags = 0
	, LPSTARTUPINFO lpStartupInfo = NULL
	, LPVOID lpEnvironment = NULL
	, LPCTSTR lpCurrentDirectory = NULL
	, LPHANDLE lphProcess = NULL
	, LPHANDLE lphThread = NULL
	, LPDWORD lpnProcessId = NULL
	, LPDWORD lpnThreadId = NULL
	);

Немного облегченная версия RSDN::CreateProcess().

inline BOOL CreateProcessAsUser
	( HANDLE hToken
	, LPCTSTR lpApplicationName
	, LPSTTR lpCommandLine
	, LPSECURITY_ATTRIBUTES lpProcessAttributes
	, LPSECURITY_ATTRIBUTES lpThreadAttributes
	, BOOL bInheritHandles
	, DWORD nCreationFlags
	, LPVOID lpEnvironment
	, LPCTSTR lpCurrentDirectory
	, LPSTARTUPINFO lpStartupInfo
	, LPHANDLE lphProcess = NULL
	, LPHANDLE lphThread = NULL
	, LPDWORD lpnProcessId = NULL
	, LPDWORD lpnThreadId = NULL
	);
inline BOOL CreateProcessAsUser
	( HANDLE hToken
	, LPCTSTR lpApplicationName
	, LPTSTR lpCommandLine
	, DWORD nCreationFlags = 0
	, LPSTARTUPINFO lpStartupInfo = NULL
	, LPVOID lpEnvironment = NULL
	, LPCTSTR lpCurrentDirectory = NULL
	, LPHANDLE lphProcess = NULL
	, LPHANDLE lphThread = NULL
	, LPDWORD lpnProcessId = NULL
	, LPDWORD lpnThreadId = NULL
	);
inline BOOL CreateProcessWithLogon
	( LPCWSTR lpUsername
	, LPCWSTR lpDomain
	, LPCWSTR lpPassword
	, DWORD   nLogonFlags
	, LPCWSTR lpApplicationName
	, LPWSTR lpCommandLine
	, DWORD nCreationFlags = 0
	, LPSTARTUPINFOW lpStartupInfo = NULL
	, LPVOID lpEnvironment = NULL
	, LPCWSTR lpCurrentDirectory = NULL
	, LPHANDLE lphProcess = NULL
	, LPHANDLE lphThread = NULL
	, LPDWORD lpnProcessId = NULL
	, LPDWORD lpnThreadId = NULL
	);
inline BOOL CreateProcessWithToken
	( HANDLE hToken
	, DWORD nLogonFlags
	, LPCWSTR lpApplicationName
	, LPWSTR lpCommandLine
	, DWORD nCreationFlags = 0
	, LPSTARTUPINFOW lpStartupInfo = NULL
	, LPVOID lpEnvironment = NULL
	, LPCWSTR lpCurrentDirectory = NULL
	, LPHANDLE lphProcess = NULL
	, LPHANDLE lphThread = NULL
	, LPDWORD lpnProcessId = NULL
	, LPDWORD lpnThreadId = NULL
	);

Еще вариации на тему ::CreateProcess()

static HANDLE CreateRemoteThreadEx
	( HANDLE hProcess
	, LPSECURITY_ATTRIBUTES lpThreadAttributes
	, SIZE_T nStackSize
	, LPTHREAD_START_ROUTINE lpStartAddress
	, SIZE_T nStartRoutineSize
	, LPVOID lpParameter = NULL
	, SIZE_T nParameterSize = 0
	, DWORD nCreationFlags = 0
	, LPDWORD lpnThreadId = NULL
	, LPVOID *lplpCodeRemote = NULL
	);
inline HANDLE CreateRemoteThreadEx
	( HANDLE hProcess
	, LPTHREAD_START_ROUTINE lpStartAddress
	, SIZE_T nStartRoutineSize
	, LPVOID lpParameter = NULL
	, SIZE_T nParameterSize = 0
	, DWORD nCreationFlags = 0
	, LPDWORD lpnThreadId = NULL
	, LPVOID *lplpCodeRemote = NULL
	);

Аналог стандартной ::CreateRemoteThread(), с тем отличаем, что эти функции сначала копируют в указанный процесс саму процедуру для выполнения в "чужом" процессе и ее параметры.

inline BOOL FreeRemoteThreadMemory
	( HANDLE hProcess
	, LPVOID lpCodeRemote
	, SIZE_T nStartRoutineSize
	, SIZE_T nParameterSize = 0
	);

Освобождает память, выделенную в RSDN::CreateRemoteThreadEx(). Эту функцию следует вызывать только после того, как созданная нить будет завершена. Поскольку выделение памяти производится в другом процессе и без его ведома, то ее следует освободить явно. В противном случае, по завершении нити, память, выделенная в том процессе так и останется не освобожденной до его завершения.

Вспомогательные функции (cmodule.h)

inline bool IsValidModule
	( HMODULE h
	);

Версия IsValidHandle(), специально предназначенная для проверки хендлов модулей.

inline BOOL DuplicateModule
	( IN HMODULE hSource
	, OUT HMODULE *lpDest
	);

То же, что и DuplicateHandle, только для модулей.

inline HMODULE LoadLibraryRelativeToModule
	( IN HMODULE hSource
	, IN LPCSTR lpLibFileName
	);

Загружает .dll по относительному пути, задаваемом хендлом модуля. Может пригодиться, если нужно загрузить .dll из другой .dll, расположенной в другом каталоге, чем .exe.

Что нового

Апрель 2004

• Поддержка асинхронных процедур (APC) в Wait() функциях.
• Новый класс-обертка для HINSTANCE (HMODULE).
• Типизированные Read()/Write()/IoControl()/т.п.
• Улучшены CCompletionPortT, CFileMappingT
• Исправлены незначительные ошибки и опечатки.

Сообщений 26    Оценка 1440 [+3/-0]         Оценить