функция lineHandoffA (tapi.h)

Функция lineHandoff предоставляет владение указанным вызовом к другому приложению. Приложение может быть указано непосредственно его именем файла или косвенно как приложение с наивысшим приоритетом, которое обрабатывает вызовы указанного режима мультимедиа.

Синтаксис

LONG lineHandoffA(
  HCALL  hCall,
  LPCSTR lpszFileName,
  DWORD  dwMediaMode
);

Параметры

hCall

Дескриптор вызова, который будет передан. Приложение должно быть владельцем вызова. Состояние вызова hCall может быть любым состоянием.

lpszFileName

Указатель на строку null-terminated. Если этот параметр указателя не являетсяNULL, он содержит имя файла приложения, которое является целью передачи. Если null, целевой объект передачи является самым приоритетным приложением, которое открыло строку для привилегий владельца для указанного режима мультимедиа. Допустимое имя файла не включает путь к файлу.

dwMediaMode

Режим мультимедиа, используемый для идентификации целевого объекта для косвенной передачи. Параметр dwMediaMode косвенно определяет целевое приложение, которое должно получить владение вызовом. Этот параметр игнорируется, если lpszFileName не NULL. Этот параметр использует только одну из констант LINEMEDIAMODE_.

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

Возвращает ноль, если запрос выполнен успешно или отрицательный номер ошибки, если возникает ошибка. Возможные возвращаемые значения:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_TARGETNOTFOUND, LINEERR_INVALPOINTER, LINEERR_TARGETSELF, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_NOTOWNER.

Замечания

Функция lineHandoff возвращает LINEERR_TARGETSELF, если вызывающее приложение попыталось непрямую передачу (то есть задайте параметру lpszFileName значение NULL) и TAPI определил, что приложение является самым приоритетным приложением для заданного режима мультимедиа. Если возвращается LINEERR_TARGETNOTFOUND, целевой объект для передачи вызовов не найден. Это может произойти, если именованное приложение не открыло ту же строку с LINECALLPRIVILEGE_OWNER битом в параметре dwPrivileges dwPrivilegeslineOpen. Или, в случае передачи в режиме мультимедиа, ни одно приложение не открыло ту же строку с LINECALLPRIVILEGE_OWNER битом в параметре dwPrivilegeslineOpen и с режимом мультимедиа, указанным в параметре dwMediaModeslineOpen.

Передача вызовов позволяет передавать вызов между приложениями. Существует два типа передачи. В первом типе, если приложение знает имя файла целевого приложения, оно может просто указать это имя файла. Если экземпляр целевого приложения открыл устройство линии, владение вызовом передается другому приложению; В противном случае передача завершается ошибкой и возвращается ошибка. Эта форма передачи завершается успешно, если дескриптор вызова передается тому же имени файла, что и приложение, запрашивающее передачу.

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

Функция lineHandoff не изменяет режим мультимедиа вызова. Чтобы изменить режим мультимедиа вызова, приложение должно использовать lineSetMediaMode в вызове, указав новый режим мультимедиа. Это изменяет режим мультимедиа вызова, как хранящийся в структуре LINECALL INFO вызова.

Если передача выполнена успешно, принимающее приложение получает LINE_CALLSTATE сообщение для вызова. Это сообщение указывает, что принимающее приложение имеет права владельца на вызов (dwParam3). Кроме того, возможно, изменилось количество владельцев и (или) мониторов для звонка. Это сообщается сообщением LINE_CALLINFO, а принимающее приложение может вызвать lineGetCallStatus и lineGetCallInfo, чтобы получить дополнительные сведения о полученном вызове.

Принимающее приложение должно сначала проверить режим мультимедиа в LINECALLINFO. Если установлен только один флаг режима мультимедиа, вызов официально является этим режимом мультимедиа, и приложение может действовать соответствующим образом. Если заданы флаги режима мультимедиа UNKNOWN и других режимов мультимедиа, то режим мультимедиа вызова официально неизвестен, но предполагается, что один из режимов мультимедиа, для которых установлен флаг в LINECALLINFO. Приложение должно предположить, что он должен проверять режим мультимедиа с наивысшим приоритетом.

Если проба успешно выполнена (либо для этого режима мультимедиа, либо для другого), приложение должно задать член режима мультимедиа в LINECALLINFO в один режим мультимедиа, который был распознан. Если флаг режима мультимедиа соответствует LINECALLINFO режиме мультимедиа, приложение может действовать соответствующим образом. Если он делает определение для другого режима мультимедиа, он должен сначала передать вызов к этому режиму мультимедиа.

Если проба завершается ошибкой, приложение должно очистить соответствующий флаг режима мультимедиа в lineCALLINFO и передать вызов, указав dwMediaMode как LINEMEDIAMODE_UNKNOWN. Он также должен освободить свой дескриптор вызова (или вернуться к мониторингу).

Если ни один из режимов мультимедиа не удалось определить, только флаг UNKNOWN остается установленным в поле режима мультимедиа LINECALLINFO в то время, когда приложение мультимедиа пытается передать вызов в UNKNOWN. Последний lineHandoff завершается ошибкой, если приложение является единственным оставшимся владельцем вызова. Это сообщает приложению, что он должен удалить вызов и отменить его дескриптор, в этом случае вызов будет отменен. Привилегии вызывающего приложения к вызову не изменяются этой операцией, но приложение может изменить свои привилегии на вызов с помощью lineSetCallPrivilege.

Заметка

Заголовок tapi.h определяет lineHandoff как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
целевая платформа	Виндоус
заголовка	tapi.h
библиотеки	Tapi32.lib
DLL	Tapi32.dll

См. также

Справочник по службам базовой телефонии

Обзор раздаток

LINECALLINFO

Обзор TAPI 2.2

lineGetCallStatus

lineOpen

lineSetCallPrivilege

lineSetMediaMode