Функция lineHandoff (tapi.h)

Статья
08/26/2023

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

Синтаксис

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

Параметры

hCall

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

lpszFileName

Указатель на строку, завершаемую null. Если этот параметр указателя не равен 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объекта lineOpen. Или в случае передачи в режиме мультимедиа ни одно приложение не открыло ту же строку с битом LINECALLPRIVILEGE_OWNER в параметре dwPrivilegeslineOpen и режимом мультимедиа, указанным в параметре dwMediaModesдля lineOpen.

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

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

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

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

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

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

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

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