Función lineForward (tapi.h)

Artículo
08/26/2023

La función 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 actualmente en vigor.

Sintaxis

LONG lineForward(
  HLINE                   hLine,
  DWORD                   bAllAddresses,
  DWORD                   dwAddressID,
  LPLINEFORWARDLIST const lpForwardList,
  DWORD                   dwNumRingsNoAnswer,
  LPHCALL                 lphConsultCall,
  LPLINECALLPARAMS const  lpCallParams
);

Parámetros

hLine

Identificador del dispositivo de línea.

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 .

dwAddressID

Dirección en la línea especificada cuyas llamadas entrantes se van a reenviar. Este parámetro se omite si bAllAddresses es TRUE.

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 que describe las instrucciones de reenvío específicas, de tipo LINEFORWARDLIST.

dwNumRingsNoAnswer

Número de anillos antes de que una llamada 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.

lphConsultCall

Puntero a una ubicación HCALL. En algunos entornos de telefonía, esta ubicación se carga con un identificador para una llamada de consulta que se usa para consultar a la parte a la que se reenvía y la aplicación se convierte en el único propietario inicial de esta llamada. Este puntero debe ser válido incluso en entornos en los que el reenvío de llamadas no requiere una llamada de consulta. Este identificador se establece en NULL si no se crea ninguna llamada de consulta.

lpCallParams

Puntero a una estructura de tipo LINECALLPARAMS. Este puntero se omite a menos que lineForward requiera el establecimiento de una llamada al destino de reenvío (y se devuelve lphConsultCall , 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 hConsultCall.

Valor devuelto

Devuelve un identificador de solicitud positivo si la función se completa de forma asincrónica o un número de error negativo si se produce un error. El parámetro dwParam2 del mensaje de LINE_REPLY correspondiente es cero si la función se realiza correctamente o es un número de error negativo si se produce un error. Los valores devueltos posibles son:

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

Comentarios

Un reenvío correcto indica solo que el proveedor de servicios ha aceptado la solicitud, no que el reenvío esté configurado en el modificador. Un mensaje de LINE_ADDRESSSTATE (reenvío) proporciona confirmación para el reenvío que se ha configurado en el conmutador.

El reenvío de 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 la antigua. El reenvío se puede cancelar especificando un puntero NULL como lpForwardList. Si se especifica una dirección de destino NULL para una entrada en 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, por 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.

Dado que es posible que un proveedor de servicios no conozca el estado de reenvío de la dirección "para asegurarse" (es decir, es posible que se haya reenviado o no se haya reenviado de forma desconocida), lineForward se realiza 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 que no haya ningún reenvío en vigor se realice correctamente. Esto se debe a que no hay "unforwarding", solo puede cambiar el conjunto anterior 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. 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ógica, 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 reenvío no afectado).

Invocar 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.