Função OpenMutexW (synchapi.h)

Artigo
08/26/2023

Abre um objeto mutex nomeado existente.

Sintaxe

HANDLE OpenMutexW(
  [in] DWORD   dwDesiredAccess,
  [in] BOOL    bInheritHandle,
  [in] LPCWSTR lpName
);

Parâmetros

[in] dwDesiredAccess

O acesso ao objeto mutex. Somente o direito de acesso SYNCHRONIZE é necessário para usar um mutex; para alterar a segurança do mutex, especifique MUTEX_ALL_ACCESS. A função falhará se o descritor de segurança do objeto especificado não permitir o acesso solicitado para o processo de chamada. Para obter uma lista de direitos de acesso, consulte Segurança do objeto de sincronização e direitos de acesso.

[in] bInheritHandle

Se esse valor for TRUE, os processos criados por esse processo herdarão o identificador. Caso contrário, os processos não herdam esse identificador.

[in] lpName

O nome do mutex a ser aberto. Comparações de nomes diferenciam maiúsculas de minúsculas.

Essa função pode abrir objetos em um namespace privado. Para obter mais informações, consulte Namespaces de objeto.

Serviços de Terminal: O nome pode ter um prefixo "Global" ou "Local" para abrir explicitamente um objeto no namespace global ou de sessão. O restante do nome pode conter qualquer caractere, exceto o caractere de barra invertida (\). Para obter mais informações, consulte Namespaces de objeto kernel.

Nota A alternância rápida de usuário é implementada usando sessões de Serviços de Terminal. O primeiro usuário a fazer logon usa a sessão 0, o próximo usuário a fazer logon usa a sessão 1 e assim por diante. Os nomes de objeto kernel devem seguir as diretrizes descritas para os Serviços de Terminal para que os aplicativos possam dar suporte a vários usuários.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um identificador para o objeto mutex.

Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.

Se um mutex nomeado não existir, a função falhará e GetLastError retornará ERROR_FILE_NOT_FOUND.

Comentários

A função OpenMutex permite que vários processos abram identificadores do mesmo objeto mutex. A função só terá êxito se algum processo já tiver criado o mutex usando a função CreateMutex . O processo de chamada pode usar o identificador retornado em qualquer função que exija um identificador para um objeto mutex, como as funções de espera, sujeito às limitações do acesso especificado no parâmetro dwDesiredAccess .

O identificador pode ser duplicado usando a função DuplicateHandle . Use a função CloseHandle para fechar o identificador. O sistema fecha o identificador automaticamente quando o processo é encerrado. O objeto mutex é destruído quando seu último identificador é fechado.

Se o aplicativo multithread precisar criar, abrir e fechar repetidamente um objeto mutex nomeado, poderá ocorrer uma condição de corrida. Nessa situação, é melhor usar CreateMutex em vez de OpenMutex, pois CreateMutex abre um mutex se ele existir e o cria se não existir.

Exemplos

Para obter um exemplo que usa OpenMutex, consulte Usando objetos nomeados.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	synchapi.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll