Функция RpcServerListen (rpcdce.h)

Статья
08/25/2023

Функция RpcServerListen сообщает библиотеке времени выполнения RPC прослушивать удаленные вызовы процедур. Эта функция не влияет на интерфейсы автоматического прослушивания; Используйте RpcServerRegisterIfEx , если вам нужны эти функции.

Синтаксис

RPC_STATUS RpcServerListen(
  unsigned int MinimumCallThreads,
  unsigned int MaxCalls,
  unsigned int DontWait
);

Параметры

MinimumCallThreads

Указание времени выполнения RPC, указывающее минимальное количество потоков вызовов, которые должны быть созданы и поддерживаться на данном сервере. Это значение является лишь подсказкой и интерпретируется по-разному в разных версиях Windows. В Windows XP это значение — количество ранее созданных потоков в каждом пуле потоков, создаваемых во время выполнения RPC. Приложение должно указать один для этого параметра и отложить решения о создании потока на время выполнения RPC.

MaxCalls

Рекомендуемое максимальное количество одновременных удаленных вызовов процедур, которые может выполнять сервер. Чтобы обеспечить эффективную производительность, библиотеки времени выполнения RPC интерпретируют параметр MaxCalls как рекомендуемое ограничение, а не как абсолютную верхнюю границу.

Используйте RPC_C_LISTEN_MAX_CALLS_DEFAULT, чтобы указать значение по умолчанию.

DontWait

Флаг, управляющий возвратом из RpcServerListen. Значение, отличное от нуля, указывает, что RpcServerListen должен вернуться сразу после завершения обработки функции. Нулевое значение указывает, что RpcServerListen не должен возвращать, пока не будет вызвана функция RpcMgmtStopServerListening и все удаленные вызовы не будут завершены.

Возвращаемое значение

Значение	Значение
RPC_S_OK	Вызов выполнен успешно.
RPC_S_ALREADY_LISTENING	Сервер уже прослушивает.
RPC_S_NO_PROTSEQS_REGISTERED	Нет зарегистрированных последовательностей протоколов.
RPC_S_MAX_CALLS_TOO_SMALL	Максимальное значение вызовов слишком мало.

Примечание Список допустимых кодов ошибок см. в разделе Возвращаемые значения RPC.

Сервер вызывает RpcServerListen , когда сервер готов к обработке удаленных вызовов процедур. RPC позволяет серверу одновременно обрабатывать несколько вызовов. Параметр MaxCalls рекомендует максимальное количество одновременных удаленных вызовов процедур, которые должен выполнять сервер.

Значение MaxCalls не должно быть равным нулю и должно быть больше MinimumCallThreads. Значения, превышающие 0x7FFFFFFF, 0x7FFFFFFF без предварительного уведомления.

Windows XP/2000: Установка для параметра MaxCalls значения RPC_C_LISTEN_MAX_CALLS_DEFAULT удаляет ограничение на одновременные удаленные вызовы процедур, а не устанавливает для него определенное константой значение 1234. При снятии ограничения на максимальное количество одновременных вызовов удаленных процедур допускается столько одновременных вызовов, сколько может обработать компьютер. Такое поведение обеспечивает повышенную эффективность во время выполнения RPC.

Серверное приложение отвечает за управление параллелизмом между подпрограммами диспетчера сервера, так как каждая подпрограмма выполняется в отдельном потоке.

Если параметр DontWait имеет нулевое значение, библиотека времени выполнения RPC продолжает прослушивать удаленные вызовы процедур (то есть подпрограмма не возвращается в серверное приложение), пока не произойдет одно из следующих событий:

Одна из подпрограмм диспетчера серверного приложения вызывает RpcMgmtStopServerListening.
Клиент вызывает удаленную процедуру, предоставляемую сервером, которая направляет сервер на вызов RpcMgmtStopServerListening.
Клиент вызывает RpcMgmtStopServerListening с дескриптором привязки к серверу.

После получения запроса на остановку прослушивания библиотека времени выполнения RPC перестает принимать новые вызовы удаленных процедур для всех зарегистрированных интерфейсов. Выполнение вызовов разрешено, включая обратные вызовы. После завершения всех вызовов RpcServerListen возвращается вызывающей объекту.

Если параметр DontWait имеет ненулевое значение, RpcServerListen возвращается на сервер сразу после обработки всех инструкций, связанных с функцией. Функцию RpcMgmtWaitServerListen можно использовать для выполнения операции ожидания, обычно связанной с RpcServerListen.

Примечание Реализация RPC Microsoft RPC для RpcServerListen включает два дополнительных параметра, которые не отображаются в спецификации DCE: DontWait и MinimumCallThreads.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	rpcdce.h (включая Rpc.h)
Библиотека	Rpcrt4.lib
DLL	Rpcrt4.dll