Функция DuplicateHandle

Функция DuplicateHandle делает копию дескриптора объекта. Продублированный дескриптор относится к тому же самому объекту, что и исходный дескриптор. Поэтому, любое изменение объекта отражается через оба дескриптора. Например, дескриптор файла, зарегистрированный для текущего файла, является всегда одним и тем же для обоих дескрипторов.

Синтаксис
 
BOOL DuplicateHandle(
  HANDLE hSourceProcessHandle,  // дескриптор процесса - источника 
  HANDLEhSourceHandle,          // дубликат дескриптора
  HANDLE hTargetProcessHandle,  // дескриптор целевого процесса
  LPHANDLE lpTargetHandle,      // дубликат дескриптора
  DWORD dwDesiredAccess,        // запрос доступа
  BOOL bInheritHandle,          // параметр наследования дескриптора
  DWORD dwOptions               // необязательные действия
); 
 
Параметры

hSourceProcessHandle

[in] Дескриптор процесса, дескриптор которого дублируется.

Windows NT /2000/XP: дескриптор должен иметь право доступа PROCESS_DUP_HANDLE. Для получения дополнительной информации, см. статью Защита процесса и права доступа.

hSourceHandle

[in] Дескриптор, который дублируется. Это открытый дескриптор объекта, который является правильным применительно к исходному процессу. Перечень объектов, дескрипторы которых могут быть продублированы, см. нижеследующем разделе Замечаний.

hTargetProcessHandle

[in] Дескриптор процесса, который должен получить продублированный дескриптор. Дескриптор должен иметь право доступа PROCESS_DUP_HANDLE.

lpTargetHandle

[out] Указатель на переменную, которая получает значение продублированного дескриптора. Это значение дескриптора правильно применительно к целевому процессу.

Если параметр lpTargetHandle имеет значение ПУСТО (NULL), функция делает копию дескриптора, но не возвращает значение продублированного дескриптора вызывающей программе. Это поведение существует только для совместимости вниз с предшествующими версиями этой функции. Вы не должны использовать эту функцию, поскольку будете терять системные ресурсы до тех пор, пока не целевой процесс не закончит свою работу.

dwDesiredAccess

[in] Доступ, требуемый для нового дескриптора. Перечень флажков, которые могут быть установлены для каждого типа объекта, см. в нижеследующем разделе Замечаний.

Этот параметр игнорируется, если параметр dwOptions устанавливает флажок DUPLICATE_SAME_ACCESS. Иначе, флажки, которые могут быть установлены, зависят от типа объекта, дескриптор которого должен быть продублирован.

bInheritHandle

[in] Указывает, является ли дескриптор наследуемым. Если он - ИСТИНА (TRUE), продублированный дескриптор может быть унаследован новыми процессами, созданными целевым процессом. Если он - ЛОЖЬ (FALSE), новый дескриптор не может быть унаследован.

dwOptions

[in] Необязательные действия. Этот параметр может быть нулевой, или любой комбинацией следующих значений.

 

Значение

Предназначение

DUPLICATE_CLOSE_SOURCE

Закрывает исходный дескриптор. Это происходит независимо от какого-либо возвращенного состояния ошибки. 

DUPLICATE_SAME_ACCESS

Игнорирует параметр dwDesiredAccess. Продублированный дескриптор имеет тот же самый доступ, что и исходный дескриптор. 

 
Возвращаемые значения

Если функция завершается успешно, величина возвращаемого значения - не ноль.

Если функция завершается с ошибкой, величина возвращаемого значения - ноль. Чтобы получать расширенные данные об ошибках, вызовите GetLastError.

Замечания

Функция DuplicateHandle может вызываться или исходным процессом, или целевым процессом. Она может также быть вызвана, где исходный и целевой процесс - одно и то же. Например, процесс может использовать DuplicateHandle, чтобы создать ненаследуемый дубликат наследуемого дескриптора, или дескриптора с другими правами доступа, чем исходный дескриптор.

Процесс дублирования использует функцию GetCurrentProcess, чтобы получить свой собственный дескриптор. Чтобы получить другой дескриптор процесса, может быть необходимо использовать некоторую форму межпроцессорного взаимодействия (например, именованный канал или совместно используемую память), чтобы сообщить идентификатор процесса процессу дублирования. Этот идентификатор затем используется в функции OpenProcess, чтобы открыть дескриптор.

Если процесс, который вызывает функцию DuplicateHandle - не целевой процесс, процесс дублирования должен использовать межпроцессорную связь, чтобы передать значение продублированного дескриптора целевому процессу.

DuplicateHandle может дублировать дескрипторы ниже перечисленных типов объектов.

Объект

Описание

Признак доступа (Access token)

Дескриптор возвращается функцией CreateRestrictedToken, DuplicateToken, DuplicateTokenEx, OpenProcessToken, или OpenThreadToken.

Устройство связи (Communications device)

Дескриптор возвращается функцией CreateFile. 

Консольный ввод данных (Console input)

Дескриптор возвращается функцией CreateFile, когда установлен CONIN$, или функцией GetStdHandle, когда установлен флажок STD_INPUT_HANDLE. Консольные дескрипторы могут быть дублированы для использования только в том же самом процессе. 

Экранный буфер консоли (Console screen buffer)

Дескриптор возвращается функцией CreateFile, когда установлен CONOUT$, или функцией GetStdHandle, когда установлен флажок STD_OUTPUT_HANDLE. Консольные дескрипторы могут быть продублированы для использования только в том же самом процессе. 

Рабочий стол (Desktop)

Дескриптор возвращается функцией GetThreadDesktop. 

Каталог (Directory)

Дескриптор возвращается функцией CreateDirectory. 

Событие (Event)

Дескриптор возвращается функцией CreateEvent или OpenEvent. 

Файл (File)

Дескриптор возвращается функцией CreateFile. 

Файл, отображаемый в память (File mapping)

Дескриптор возвращается функцией CreateFileMapping. 

Задание (Job)

Дескриптор возвращается функцией CreateJobObject. 

Почтовый ящик в ядре системы (Mailslot)

Дескриптор возвращается функцией CreateMailslot. 

Мьютекс (Mutex)

Дескриптор возвращается функцией CreateMutex или OpenMutex. 

Канал (Pipe)

Дескриптор именованного канала возвращается функцией CreateNamedPipe или CreateFile. Дескриптор анонимного канала возвращается функцией CreatePipe. 

Процесс (Process)

Дескриптор возвращается функцией CreateProcess, GetCurrentProcess или OpenProcess. 

Ключ системного реестра (Registry key)

Windows NT/2000/XP: Дескриптор возвращается функцией RegCreateKey, RegCreateKeyEx, RegOpenKey или RegOpenKeyEx. 

Обратите внимание! те дескрипторы ключа системного реестра, возвращенные функцией RegConnectRegistry не могут быть использованы при вызове для DuplicateHandle.

Windows 95/98/Me: Вы не можете использовать DuplicateHandle, чтобы продублировать дескрипторы ключа системного реестра.

Семафор (Semaphore)

Дескриптор возвращается функцией CreateSemaphore или OpenSemaphore. 

Сокет (Socket)

Дескриптор возвращается функцией socket или accept. 

Поток (Thread)

Дескриптор возвращается функцией CreateProcess, CreateThread, CreateRemoteThread или GetCurrentThread. 

Таймер (Timer)

Дескриптор возвращается функцией CreateWaitableTimer или OpenWaitableTimer. 

Оконный режим терминала (Window station)

Дескриптор возвращается функцией GetProcessWindowStation. 

 

Обратите внимание! что функция DuplicateHandle не должна использоваться для дублирования дескрипторов портов завершения ввода-вывода. В этом случае, не возвращается никакой ошибки, но продублированный дескриптор не может быть использован.

В дополнение к флажку STANDARD_RIGHTS_REQUIRED, нижеследующие права доступа могут быть определены в параметре dwDesiredAccess для других типов объекта:

Защита рабочего стола и права доступа

Защита файла и каталога и права доступа

Защита файла, отображаемого в памяти и права доступа

Защита объекта задания и права доступа

Защита процесса и права доступа

 
Защита ключа системного реестра и права доступа

Защита объекта синхронизации и права доступа

Защита потока и права доступа

Защита оконного режима терминала и права доступа

В некоторых случаях, новый дескриптор может иметь большее количество прав доступа, чем исходный дескриптор. Однако в других случаях, DuplicateHandle не может создать дескриптор с большим количеством прав доступа, чем оригинал. Например, дескриптор файла, созданный с правом доступа GENERIC_READ не может быть продублирован так, чтобы он имел, и право доступа GENERIC_READ и GENERIC_WRITE.

Код примера

Пример смотри в статье Создание дочернего процесса с переназначенным вводом и выводом.

Смотри также

Краткий обзор Дескрипторы и объекты, Функции дескрипторов и объектов, CloseHandle

 

Размещение и совместимость DuplicateHandle

Windows. NET Server

Да

Windows XP

Да

Windows 2000

Да

Windows NT

Да

Windows Me

Да

Windows 98

Да

Windows 95

Да

Используемая библиотека

Kernel32.lib

Заголовочный файл

  

- объявлено в

Winbase.h

- включено в

Windows.h

Unicode

 
Нет

Замечания по платформе

Не имеется

 

Назад в оглавление
На главную страницу
На оглавление справки

Hosted by uCoz