Função CreateMutexExA (synchapi.h)
Cria ou abre um objeto mutex nomeado ou sem nome e retorna um identificador para o objeto .
Sintaxe
HANDLE CreateMutexExA(
[in, optional] LPSECURITY_ATTRIBUTES lpMutexAttributes,
[in, optional] LPCSTR lpName,
[in] DWORD dwFlags,
[in] DWORD dwDesiredAccess
);
Parâmetros
[in, optional] lpMutexAttributes
Um ponteiro para uma estrutura SECURITY_ATTRIBUTES . Se esse parâmetro for NULL, o identificador mutex não poderá ser herdado por processos filho.
O membro lpSecurityDescriptor da estrutura especifica um descritor de segurança para o novo mutex. Se lpMutexAttributes for NULL, o mutex obterá um descritor de segurança padrão. As ACLs no descritor de segurança padrão para um mutex vêm do token primário ou de representação do criador. Para obter mais informações, consulte Segurança do objeto de sincronização e direitos de acesso.
[in, optional] lpName
O nome do objeto mutex. O nome é limitado a MAX_PATH caracteres. A comparação de nomes diferencia maiúsculas de minúsculas.
Se lpName for NULL, o objeto mutex será criado sem um nome.
Se lpName corresponder ao nome de um evento existente, semáforo, temporizador de espera, trabalho ou objeto de mapeamento de arquivo, a função falhará e a função GetLastError retornará ERROR_INVALID_HANDLE. Isso ocorre porque esses objetos compartilham o mesmo namespace.
O nome pode ter um prefixo "Global" ou "Local" para criar explicitamente o 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. A alternância rápida de usuário é implementada usando sessões de Serviços de Terminal. 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.
O objeto pode ser criado em um namespace privado. Para obter mais informações, consulte Namespaces de objeto.
[in] dwFlags
Esse parâmetro pode ser 0 ou o valor a seguir.
| Valor | Significado |
|---|---|
|
O criador do objeto é o proprietário inicial do mutex. |
[in] dwDesiredAccess
A máscara de acesso para o objeto mutex. Para obter uma lista de direitos de acesso, consulte Segurança do objeto de sincronização e direitos de acesso.
Retornar valor
Se a função for bem-sucedida, o valor retornado será um identificador para o objeto mutex recém-criado.
Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.
Se o mutex for um mutex nomeado e o objeto existir antes dessa chamada de função, o valor retornado será um identificador para o objeto existente e a função GetLastError retornará ERROR_ALREADY_EXISTS.
Comentários
Se você estiver usando um mutex nomeado para limitar seu aplicativo a uma única instância, um usuário mal-intencionado poderá criar esse mutex antes de você e impedir que seu aplicativo seja iniciado. Para evitar essa situação, crie um mutex nomeado aleatoriamente e armazene o nome para que ele só possa ser obtido por um usuário autorizado. Como alternativa, você pode usar um arquivo para essa finalidade. Para limitar seu aplicativo a uma instância por usuário, crie um arquivo bloqueado no diretório de perfil do usuário.
Qualquer thread do processo de chamada pode especificar o identificador mutex-object em uma chamada para uma das funções de espera. As funções de espera de objeto único retornam quando o estado do objeto especificado é sinalizado. As funções de espera de vários objetos podem ser instruídas a retornar quando qualquer um ou quando todos os objetos especificados são sinalizados. Quando uma função de espera retorna, o thread em espera é liberado para continuar sua execução.
O estado de um objeto mutex é sinalizado quando ele não pertence a nenhum thread. O thread de criação pode usar o parâmetro dwFlags para solicitar a propriedade imediata do mutex. Caso contrário, um thread deve usar uma das funções de espera para solicitar a propriedade. Quando o estado do mutex é sinalizado, um thread de espera recebe a propriedade, o estado do mutex é alterado para não atribuído e a função de espera retorna. Apenas um thread pode ter um mutex a qualquer momento. O thread proprietário usa a função ReleaseMutex para liberar sua propriedade.
O thread que possui um mutex pode especificar o mesmo mutex em chamadas de função de espera repetidas sem bloquear sua execução. Normalmente, você não esperaria repetidamente pelo mesmo mutex, mas esse mecanismo impede que um thread se deadlocke enquanto aguarda um mutex que ele já possui. No entanto, para liberar sua propriedade, o thread deve chamar ReleaseMutex uma vez para cada vez que o mutex satisfaz uma espera.
Dois ou mais processos podem chamar CreateMutex para criar o mesmo mutex nomeado. O primeiro processo realmente cria o mutex e os processos subsequentes com direitos de acesso suficientes simplesmente abrem um identificador para o mutex existente. Isso permite que vários processos obtenham identificadores do mesmo mutex, enquanto aliviam o usuário da responsabilidade de garantir que o processo de criação seja iniciado primeiro. Ao usar essa técnica, você não deve usar o sinalizador CREATE_MUTEX_INITIAL_OWNER ; caso contrário, pode ser difícil ter certeza de qual processo tem propriedade inicial.
Vários processos podem ter identificadores do mesmo objeto mutex, permitindo o uso do objeto para sincronização entre processos. Os seguintes mecanismos de compartilhamento de objetos estão disponíveis:
- Um processo filho criado pela função CreateProcess poderá herdar um identificador para um objeto mutex se o parâmetro lpMutexAttributes da herança habilitada para CreateMutex . Esse mecanismo funciona para mutexes nomeados e não nomeados.
- Um processo pode especificar o identificador para um objeto mutex em uma chamada para a função DuplicateHandle para criar um identificador duplicado que pode ser usado por outro processo. Esse mecanismo funciona para mutexes nomeados e não nomeados.
- Um processo pode especificar um mutex nomeado em uma chamada para a função [OpenMutex](./nf-synchapi-openmutexw.md) ou CreateMutex para recuperar um identificador para o objeto mutex.
Observação
O cabeçalho synchapi.h define CreateMutexEx como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | synchapi.h (inclua Windows.h no Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de