Função CreateSemaphoreExW (synchapi.h)
Cria ou abre um objeto de semáforo nomeado ou sem nome e retorna um identificador para o objeto.
Sintaxe
HANDLE CreateSemaphoreExW(
[in, optional] LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
[in] LONG lInitialCount,
[in] LONG lMaximumCount,
[in, optional] LPCWSTR lpName,
DWORD dwFlags,
[in] DWORD dwDesiredAccess
);
Parâmetros
[in, optional] lpSemaphoreAttributes
Um ponteiro para uma estrutura SECURITY_ATTRIBUTES. Se esse parâmetro for NULL, o identificador de semáforo não poderá ser herdado por processos filho.
O lpSecurityDescriptor membro da estrutura especifica um descritor de segurança para o novo semáforo. Se esse parâmetro for NULL, o semáforo obterá um descritor de segurança padrão. As ACLs no descritor de segurança padrão para um semáforo vêm do token primário ou de representação do criador.
[in] lInitialCount
A contagem inicial do objeto semáforo. Esse valor deve ser maior ou igual a zero e menor ou igual a lMaximumCount. O estado de um semáforo é sinalizado quando sua contagem é maior que zero e não atribuída quando é zero. A contagem é reduzida em um sempre que uma função de espera libera um thread que estava aguardando o semáforo. A contagem é aumentada por um valor especificado chamando a função ReleaseSemaphore.
[in] lMaximumCount
A contagem máxima para o objeto semáforo. Esse valor deve ser maior que zero.
[in, optional] lpName
Um ponteiro para uma cadeia de caracteres terminada em nulo especificando o nome do objeto semáforo. 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 de semáforo nomeado existente, os parâmetros lInitialCount e lMaximumCount serão ignorados porque eles já foram definidos pelo processo de criação. Se o parâmetro lpSemaphoreAttributes não for NULL, ele determinará se o identificador pode ser herdado.
Se lpName for NULL, o objeto semáforo será criado sem um nome.
Se lpName corresponder ao nome de um evento existente, mutex, 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 dos 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.
dwFlags
Esse parâmetro é reservado e deve ser 0.
[in] dwDesiredAccess
A máscara de acesso para o objeto semáforo. Para obter uma lista de direitos de acesso, consulte de Segurança do Objeto de Sincronização e Direitos de Acesso.
Valor de retorno
Se a função for bem-sucedida, o valor retornado será um identificador para o objeto semáforo. Se o objeto semáforo nomeado existir antes da chamada de função, a função retornará um identificador para o objeto existente e GetLastError retornará ERROR_ALREADY_EXISTS.
Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.
Observações
O estado de um objeto semáforo é sinalizado quando sua contagem é maior que zero e não atribuída quando sua contagem é igual a zero. O parâmetro lInitialCount especifica a contagem inicial. A contagem nunca pode ser menor que zero ou maior do que o valor especificado no parâmetro lMaximumCount.
Qualquer thread do processo de chamada pode especificar o identificador de objeto semáforo 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 instruidas a retornar quando qualquer um ou quando todos os objetos especificados são sinalizados. Quando uma função de espera retorna, o thread de espera é liberado para continuar sua execução. Cada vez que um thread conclui uma espera por um objeto semáforo, a contagem do objeto semáforo é decrementada por um. Quando o thread for concluído, ele chamará a função ReleaseSemaphore, que incrementa a contagem do objeto semáforo.
Vários processos podem ter identificadores do mesmo objeto semáforo, 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 pode herdar um identificador para um objeto semáforo se o lpSemaphoreAttributes parâmetro de CreateSemaphoreEx herança habilitada.
- Um processo pode especificar o identificador de objeto semáforo em uma chamada para a função DuplicateHandle para criar um identificador duplicado que pode ser usado por outro processo.
- Um processo pode especificar o nome de um objeto semáforo em uma chamada para a função OpenSemaphore ou CreateSemaphoreEx.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| servidor com suporte mínimo | Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP] |
| da Plataforma de Destino |
Windows |
| cabeçalho | synchapi.h (inclua Windows.h) |
| biblioteca | Kernel32.lib |
| de DLL |
Kernel32.dll |