función TSPI_lineForward (tspi.h)

Artículo
08/26/2023

La función TSPI_lineForward reenvía las llamadas destinadas a la dirección especificada en la línea especificada, según las instrucciones de reenvío especificadas. Cuando se reenvía una dirección de origen (dwAddressID), el modificador deselecciona las llamadas entrantes especificadas para esa dirección. Esta función proporciona una combinación de características de avance y no molestar. Esta función también puede cancelar el reenvío específico actualmente en vigor.

Sintaxis

LONG TSPIAPI TSPI_lineForward(
  DRV_REQUESTID           dwRequestID,
  HDRVLINE                hdLine,
  DWORD                   bAllAddresses,
  DWORD                   dwAddressID,
  LPLINEFORWARDLIST const lpForwardList,
  DWORD                   dwNumRingsNoAnswer,
  HTAPICALL               htConsultCall,
  LPHDRVCALL              lphdConsultCall,
  LPLINECALLPARAMS const  lpCallParams
);

Parámetros

dwRequestID

Identificador de la solicitud asincrónica.

hdLine

Identificador del proveedor de servicios a la línea que se va a reenviar.

bAllAddresses

Especifica si todas las direcciones que se originan en la línea o solo la especificada se reenvía. Si es TRUE, se reenvía todas las direcciones de la línea y dwAddressID se omite; si es FALSE, solo se reenvía la dirección especificada como dwAddressID . TAPI no valida este parámetro cuando se llama a esta función.

dwAddressID

Dirección de la línea especificada cuyas llamadas entrantes se van a reenviar. Este parámetro se omite si bAllAddresses es TRUE. TAPI no valida este parámetro cuando se llama a esta función.

Un identificador de dirección está asociado permanentemente a una dirección; el identificador permanece constante en las actualizaciones del sistema operativo.

lpForwardList

Puntero a una estructura de datos de tamaño variable de tipo LINEFORWARDLIST que describe las instrucciones de reenvío específicas.

dwNumRingsNoAnswer

Especifica el número de anillos antes de que una llamada entrante se considere una "sin respuesta". Si dwNumRingsNoAnswer está fuera del intervalo, el valor real se establece en el valor más cercano del intervalo permitido. TAPI no valida este parámetro cuando se llama a esta función.

htConsultCall

El identificador TAPI de una nueva llamada, si el proveedor de servicios debe crear dicha llamada. En algunos entornos de telefonía, el reenvío de una llamada tiene el efecto secundario de crear una llamada de consulta utilizada para consultar a la parte a la que se reenvía. En este entorno, el proveedor de servicios crea la nueva llamada de consulta y debe guardar este valor y usarlo en todas las llamadas posteriores al procedimiento LINEEVENT que notifica eventos en la llamada. Si no se crea ninguna llamada de consulta, el proveedor de servicios puede omitir este valor.

lphdConsultCall

Puntero a un HDRVCALL que representa el identificador del proveedor de servicios para la llamada. En entornos de telefonía donde el reenvío de una llamada tiene el efecto secundario de crear una llamada de consulta utilizada para consultar a la parte a la que se reenvía, el proveedor de servicios debe rellenar esta ubicación con su identificador para la llamada antes de que este procedimiento vuelva. El proveedor de servicios puede realizar devoluciones de llamada con respecto a la nueva llamada antes de que vuelva de este procedimiento. Si no se crea ninguna llamada de consulta, HDRVCALL debe dejarse NULL.

lpCallParams

Puntero a una estructura de tipo LINECALLPARAMS. El proveedor de servicios omite este puntero a menos que lineForward requiera el establecimiento de una llamada al destino de reenvío (y lphdConsultCall se devuelve, en cuyo caso lpCallParams es opcional). Si es NULL, se usan parámetros de llamada predeterminados. De lo contrario, los parámetros de llamada especificados se usan para establecer htConsultCall.

Valor devuelto

Devuelve dwRequestID o un número de error si se produce un error. El parámetro real lResult del ASYNC_COMPLETION correspondiente es cero si la función se realiza correctamente o si se produce un error. Los valores devueltos posibles son los siguientes:

LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_STRUCTURETOOSMALL.

Comentarios

El proveedor de servicios devuelve LINEERR_INVALPARAM si el parámetro de lista de reenvíos especificado contiene información no válida.

El proveedor de servicios no realiza ninguna marcación si devuelve LINEERR_INVALADDRESS.

El proveedor de servicios devuelve éxito a esta función para indicar solo que el proveedor de servicios acepta la solicitud, no que el reenvío esté configurado en el modificador. Se envía un mensaje de LINE_ADDRESSSTATE (reenvío) para proporcionar que el reenvío esté configurado en el modificador.

El reenvío de la dirección o las direcciones permanece en vigor hasta que se vuelva a llamar a esta función. La lista de reenvío más reciente reemplaza a cualquiera anterior en vigor. Si se llama a esta función, especificando un puntero NULL como lpForwardList, el proveedor de servicios debe cancelar cualquier reenvío que se realice en ese momento. Si se especifica una dirección de destino NULL para una entrada de la lista de reenvío, la operación actúa como "no molestar".

El estado de reenvío de una dirección también puede verse afectado externamente, por ejemplo, mediante acciones administrativas en el conmutador o por un usuario de otra estación. Es posible que no sea posible que el proveedor de servicios tenga en cuenta este cambio de estado y es posible que no pueda mantenerse sincronizado con el estado de reenvío conocido para el modificador. El proveedor siempre debe indicar lo que sabe que es true e indicar que el estado de reenvío es desconocido de lo contrario.

Dado que es posible que un proveedor de servicios no conozca el estado de reenvío de la dirección sin duda (es decir, es posible que se haya reenviado o no se haya reenviado de forma desconocida), TSPI_lineForward se realice correctamente a menos que no establezca las nuevas instrucciones de reenvío. Es decir, una solicitud de que se cancele todo el reenvío en un momento en el que no haya ningún reenvío en vigor. Esto se debe a que no hay ningún desenlazamiento; Solo puede invocar un nuevo conjunto de instrucciones de reenvío.

El éxito o error de esta operación no depende del conjunto anterior de instrucciones de reenvío, y lo mismo sucede al establecer instrucciones de reenvío diferentes. Si es necesario, el proveedor debe "desenviar todo" antes de establecer las nuevas instrucciones de reenvío. Dado que esto puede tardar tiempo en entornos de telefonía analógicas, un proveedor también puede querer comparar el reenvío actual con el nuevo y solo emitir instrucciones al conmutador para llegar al estado final (dejando sin cambios reenviar sin afectar).

Invocar TSPI_lineForward cuando LINEFORWARDLIST tiene dwNumEntries establecido en cero tiene el mismo efecto que proporcionar un parámetro lpForwardListNULL; cancela todo el reenvío actualmente en vigor.

Dado que el valor NULL devuelto en lphdConsultCall es la única manera de que TAPI determine si el proveedor de servicios creó una llamada de consulta, el proveedor de servicios no puede usar NULL como identificador de llamada.

Esta función difiere de la función TAPI correspondiente en que sigue el modelo de TSPI para comenzar la duración de una llamada. TAPI y el proveedor de servicios intercambian identificadores opacos que representan la llamada entre sí. Además, el proveedor de servicios puede realizar devoluciones de llamada para la nueva llamada antes de que vuelva de este procedimiento. En cualquier caso, el proveedor de servicios también debe tratar el identificador que devolvió como "todavía no válido" hasta después de que la coincidencia ASYNC_COMPLETION informe de éxito. Es decir, no debe emitir ningún mensaje para la nueva llamada ni incluirlo en recuentos de llamadas en mensajes o estructuras de datos de estado para la línea.