Função CreatePrintAsyncNotifyChannel (prnasnot.h)

Cria um canal de comunicação entre um componente de impressão hospedado pelo Spooler de Impressão, como um driver de impressão ou um monitor de porta, e um aplicativo que recebe notificações do componente.

Sintaxe

HRESULT CreatePrintAsyncNotifyChannel(
  [in]  PCWSTR                            pszName,
  [in]  PrintAsyncNotificationType        *pNotificationType,
  [in]  PrintAsyncNotifyUserFilter        eUserFilter,
  [in]  PrintAsyncNotifyConversationStyle eConversationStyle,
  [in]  IPrintAsyncNotifyCallback         *pCallback,
  [out] IPrintAsyncNotifyChannel          **ppIAsynchNotification
);

Parâmetros

[in] pszName

Um ponteiro para o nome de um servidor de impressão ou fila de impressão.

[in] pNotificationType

Um ponteiro para o GUID do esquema de dados para o tipo de notificações a serem enviadas no canal.

[in] eUserFilter

Um valor que especifica se as notificações serão enviadas para:

• Somente aplicativos que estão sendo executados como o mesmo usuário que o remetente de plug-in hospedado no Spooler de Impressão.
• Um conjunto mais amplo de aplicativos de escuta.

[in] eConversationStyle

Um valor que especifica se a comunicação é bidirecional ou unidirecional.

[in] pCallback

Um ponteiro para um objeto que o aplicativo de escuta usará para chamar de volta o componente hospedado pelo Spooler de Impressão. Isso deverá ser NULL se directionality for kUniDirectional.

[out] ppIAsynchNotification

Um ponteiro para o novo canal.

Retornar valor

HRESULT	Severidade	Significado
S_OK	SUCCESS	A função foi concluída com êxito.
CHANNEL_ALREADY_OPENED	ERROR	O canal já foi aberto.
MAX_CHANNEL_COUNT_EXCEEDED	ERROR	O número máximo de aplicativos ouvintes já se registrou para o tipo de notificação especificado com a fila ou o servidor de impressão especificado. O máximo padrão é 10.000.

 

Os valores retornados são códigos de erro COM. Como essa função pode concluir a operação com êxito, ainda retorna um HRESULT diferente de S_OK você deve usar a macro SUCCEEDED ou FAILED para determinar o sucesso da chamada. Para obter o HRESULT específico retornado pela função, use a macro HRESULT_CODE.

O exemplo de código a seguir mostra como essas macros podem ser usadas para avaliar o valor retornado.

if (SUCCEEDED(hr)){
  //Call was successful 
}

if (FAILED(hr)) {
  // Call failed 
}

if (FAILED(hr)) {
  // Call failed 
  switch (HRESULT_CODE(hr)){
    case CHANNEL_ALREADY_OPENED:
      // Some action 
      break;
    case MAX_CHANNEL_COUNT_EXCEEDED:
      // Some action 
      break;
    default:
      //Default action 
      break;
  }
} else {
  //call succeeded 
}

Para obter mais informações sobre códigos de erro do COM, confira Tratamento de erros.

Consulte PrintAsyncNotifyError para obter outros valores de retorno possíveis.

Comentários

Nota Essa é uma função de bloqueio ou síncrona e pode não retornar imediatamente. A rapidez com que essa função retorna depende de fatores de tempo de execução, como status de rede, configuração do servidor de impressão e implementação do driver de impressora— fatores difíceis de prever ao escrever um aplicativo. Chamar essa função de um thread que gerencia a interação com a interface do usuário pode fazer com que o aplicativo pareça não responder.

 

Um componente só poderá abrir um canal se ele for executado no processo do Spooler de Impressão. Por exemplo, se um aplicativo carregar um driver de impressora, o driver não poderá abrir um canal, mas um driver de impressora carregado dentro do Spooler de Impressão poderá abrir um canal. Os aplicativos de escuta podem estar dentro ou fora do processo do Spooler de Impressão.

Para fechar um canal, chame IPrintAsyncNotifyChannel::CloseChannel; no entanto, IPrintAsyncNotifyChannel::CloseChannel não pode ser chamado imediatamente após a chamada para CreatePrintAsyncNotifyChannel.

Chame IPrintAsyncNotifyChannel::Release() somente:

1. se for uma correspondência explícita a uma chamada anterior de IPrintAsyncNotifyChannel::AddRef().
2. se o canal for um canal UniDirectional e você estiver abandonando o ponteiro recebido em uma chamada bem-sucedida para CreatePrintAsyncNotifyChannel.
3. se, depois de criar um canal Bidirecional ou na implementação de IPrintNotifyAsyncCallback::OnEventNotify e:
   1. você não chamou IPrintAsyncNotifyChannel::SendNotification ou IPrintAsyncNotifyChannel::CloseChannel OR
   2. você não tentou novamente uma chamada para IPrintAsyncNotifyChannel::SendNotification ou IPrintAsyncNotifyChannel::CloseChannel que falhou em OR
   3. no lado do servidor, você não tentou novamente uma chamada para IPrintAsyncNotifyChannel::SendNotification que teve êxito com o valor retornado NO_LISTENER OR
   4. no lado do cliente, você não tentou novamente uma chamada para IPrintAsyncNotifyChannel::SendNotification que teve êxito com o valor retornado CHANNEL_ACQUIRED.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	prnasnot.h
Biblioteca	Winspool.lib
DLL	Spoolss.dll

Confira também

Client Impersonation (em inglês)

Funções da API do Spooler de impressão

Impressão