Função CreateMutexA (synchapi.h)
Cria ou abre um objeto mutex nomeado ou sem nome.
Para especificar uma máscara de acesso para o objeto, use a função CreateMutexEx .
Sintaxe
HANDLE CreateMutexA(
[in, optional] LPSECURITY_ATTRIBUTES lpMutexAttributes,
[in] BOOL bInitialOwner,
[in, optional] LPCSTR lpName
);
Parâmetros
[in, optional] lpMutexAttributes
Um ponteiro para uma estrutura SECURITY_ATTRIBUTES . Se esse parâmetro for NULL, o identificador 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] bInitialOwner
Se esse valor for TRUE e o chamador tiver criado o mutex, o thread de chamada obterá a propriedade inicial do objeto mutex. Caso contrário, o thread de chamada não obterá a propriedade do mutex. Para determinar se o chamador criou o mutex, consulte a seção Valores retornados.
[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 corresponder ao nome de um objeto mutex nomeado existente, essa função solicitará o direito de acesso MUTEX_ALL_ACCESS. Nesse caso, o parâmetro bInitialOwner é ignorado porque já foi definido pelo processo de criação. Se o parâmetro lpMutexAttributes não for NULL, ele determinará se o identificador pode ser herdado, mas seu membro descritor de segurança será ignorado.
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 troca rápida de usuário é implementada usando sessões dos Serviços de Terminal. Os nomes de objetos 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.
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
O identificador retornado por CreateMutex tem o direito de acesso MUTEX_ALL_ACCESS ; ele pode ser usado em qualquer função que exija um identificador para um objeto mutex, desde que o chamador tenha recebido acesso. Se um mutex for criado a partir de um serviço ou um thread que esteja representando um usuário diferente, você poderá aplicar um descritor de segurança ao mutex ao criá-lo ou alterar o descritor de segurança padrão para o processo de criação alterando sua DACL padrão. Para obter mais informações, consulte Segurança do objeto de sincronização e direitos de acesso.
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 forem sinalizados. Quando uma função de espera retorna, o thread de 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 sinalizador bInitialOwner para solicitar a propriedade imediata do mutex. Caso contrário, um thread deverá 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. Somente 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 atendesse a 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ê deve definir o sinalizador bInitialOwner como FALSE; 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 [OpenMutex](./nf-synchapi-openmutexw.md) ou CreateMutex para recuperar um identificador para o objeto mutex.
Exemplos
Consulte Usando objetos Mutex para obter um exemplo de CreateMutex.
Observação
O cabeçalho synchapi.h define CreateMutex 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 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 no Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |