Función lineHandoff (tapi.h)

Artículo
08/26/2023

La función lineHandoff proporciona la propiedad de la llamada especificada a otra aplicación. La aplicación puede especificarse directamente por su nombre de archivo o indirectamente como la aplicación de prioridad más alta que controla las llamadas del modo multimedia especificado.

Sintaxis

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

Parámetros

hCall

Maneje la llamada que se va a entregar. La aplicación debe ser propietario de la llamada. El estado de llamada de hCall puede ser cualquier estado.

lpszFileName

Puntero a una cadena terminada en null. Si este parámetro de puntero no es NULL, contiene el nombre de archivo de la aplicación que es el destino de la entrega. Si es NULL, el destino de entrega es la aplicación de prioridad más alta que ha abierto la línea para el privilegio de propietario para el modo multimedia especificado. Un nombre de archivo válido no incluye la ruta de acceso del archivo.

dwMediaMode

Modo multimedia usado para identificar el destino del entrega indirecto. El parámetro dwMediaMode identifica indirectamente la aplicación de destino que va a recibir la propiedad de la llamada. Este parámetro se omite si lpszFileName no es NULL. Este parámetro usa una y solo una de las LINEMEDIAMODE_ Constantes.

Valor devuelto

Devuelve cero si la solicitud se realiza correctamente o un número de error negativo si se produce un error. Los valores devueltos posibles son:

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

Comentarios

La función lineHandoff devuelve LINEERR_TARGETSELF si la aplicación que realiza la llamada intentó una entrega indirecta (es decir, establecer el parámetro lpszFileName en NULL) y TAPI determinó que la aplicación es la propia aplicación de prioridad más alta para el modo multimedia determinado. Si se devuelve LINEERR_TARGETNOTFOUND, no se encontró un destino para la entrega de la llamada. Esto puede ocurrir si la aplicación con nombre no ha abierto la misma línea con el bit LINECALLPRIVILEGE_OWNER en el parámetro dwPrivileges de lineOpen. O bien, en el caso de entrega en modo multimedia, ninguna aplicación ha abierto la misma línea con el bit LINECALLPRIVILEGE_OWNER en el parámetro dwPrivileges de lineOpen y con el modo multimedia especificado en el parámetro dwMediaModes de lineOpen.

La entrega de llamadas permite pasar la propiedad de una llamada entre las aplicaciones. Hay dos tipos de entrega. En el primer tipo, si la aplicación conoce el nombre de archivo de la aplicación de destino, simplemente puede especificar ese nombre de archivo. Si una instancia de la aplicación de destino ha abierto el dispositivo de línea, la propiedad de la llamada se pasa a la otra aplicación; de lo contrario, se produce un error en la entrega y se devuelve un error. Esta forma de entrega se realiza correctamente si el identificador de llamada se entrega al mismo nombre de archivo que la aplicación que solicita la entrega.

El segundo tipo de entrega se basa en el modo multimedia. En este caso, la aplicación especifica indirectamente la aplicación de destino mediante un modo multimedia. La aplicación de prioridad más alta que ha abierto actualmente el dispositivo de línea para ese modo multimedia es el destino para la entrega. Si no hay ninguna aplicación de este tipo, se produce un error de entrega y se devuelve un error.

La función lineHandoff no cambia el modo multimedia de una llamada. Para cambiar el modo multimedia de una llamada, la aplicación debe usar lineSetMediaMode en la llamada, especificando el nuevo modo multimedia. Esto cambia el modo multimedia de la llamada como almacenado en la estructura LINECALLINFO de la llamada.

Si la entrega se realiza correctamente, la aplicación receptora recibe un mensaje de LINE_CALLSTATE para la llamada. Este mensaje indica que la aplicación receptora tiene privilegios de propietario para la llamada (dwParam3). Además, es posible que el número de propietarios o monitores de la llamada haya cambiado. Esto se notifica mediante el mensaje de LINE_CALLINFO y la aplicación receptora puede invocar lineGetCallStatus y lineGetCallInfo para recuperar más información sobre la llamada recibida.

La aplicación receptora debe comprobar primero el modo multimedia en LINECALLINFO. Si solo se establece una marca de modo multimedia, la llamada es oficialmente de ese modo multimedia y la aplicación puede actuar en consecuencia. Si se establecen marcas UNKNOWN y otras marcas de modo multimedia, el modo multimedia de la llamada es oficialmente DESCONOCIDO, pero se supone que es de uno de los modos multimedia para los que se establece una marca en LINECALLINFO. La aplicación debe suponer que debe sondear el modo multimedia de prioridad más alta.

Si el sondeo se realiza correctamente (ya sea para ese modo multimedia o para otro), la aplicación debe establecer el miembro del modo multimedia en LINECALLINFO en el modo multimedia único que se reconoció. Si la marca del modo multimedia coincide con el modo multimedia LINECALLINFO , la aplicación puede actuar en consecuencia. Si toma una determinación para otro modo multimedia, primero debe entregar la llamada a ese modo multimedia.

Si se produce un error en el sondeo, la aplicación debe borrar la marca de modo multimedia correspondiente en LINECALLINFO y entregar la llamada, especificando dwMediaMode como LINEMEDIAMODE_UNKNOWN. También debe desasignar su identificador de llamada (o revertir a la supervisión).

Si ninguno de los modos multimedia ha realizado correctamente una determinación, solo la marca UNKNOWN permanece establecida en el campo de modo multimedia de LINECALLINFO en el momento en que la aplicación multimedia intenta entregar la llamada a UNKNOWN. Se produce un error en la línea finalHandoff si la aplicación es el único propietario restante de la llamada. Esto informa a la aplicación de que debe quitar la llamada y desasignar su identificador, en cuyo caso se abandona la llamada. Los privilegios de la aplicación invocada a la llamada no cambian en esta operación, pero la aplicación puede cambiar sus privilegios a una llamada con lineSetCallPrivilege.