TSPI_lineForward 함수(tspi.h)

아티클
03/03/2024

TSPI_lineForward 함수는 지정된 전달 지침에 따라 지정된 줄의 지정된 주소로 향하는 호출을 전달합니다. 원래 주소(dwAddressID)를 전달하면 해당 주소에 대해 지정된 수신 호출이 스위치에 의해 다른 번호로 편향됩니다. 이 함수는 전방 및 방해 금지 기능의 조합을 제공합니다. 이 함수는 현재 적용 중인 특정 전달을 취소할 수도 있습니다.

구문

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
);

매개 변수

dwRequestID

비동기 요청의 식별자입니다.

hdLine

전달할 줄에 대한 서비스 공급자의 핸들입니다.

bAllAddresses

줄의 모든 원래 주소 또는 지정된 주소만 전달할지 여부를 지정합니다. TRUE이면 줄의 모든 주소가 전달되고 dwAddressID 는 무시됩니다. FALSE이면 dwAddressID 로 지정된 주소만 전달됩니다. 이 함수가 호출될 때 TAPI에서 이 매개 변수의 유효성을 검사하지 않습니다.

dwAddressID

들어오는 호출을 전달할 지정된 줄의 주소입니다. bAllAddresses가 TRUE이면 이 매개 변수는 무시됩니다. 이 함수가 호출될 때 TAPI에서 이 매개 변수의 유효성을 검사하지 않습니다.

주소 식별자는 주소와 영구적으로 연결됩니다. 식별자는 운영 체제 업그레이드에서 일정하게 유지됩니다.

lpForwardList

특정 전달 지침을 설명하는 LINEFORWARDLIST 형식의 고정 크기 데이터 구조에 대한 포인터입니다.

dwNumRingsNoAnswer

들어오는 호출이 "응답 없음"으로 간주되기 전의 링 수를 지정합니다. dwNumRingsNoAnswer 가 범위를 벗어나면 실제 값이 허용 범위에서 가장 가까운 값으로 설정됩니다. 이 함수가 호출될 때 TAPI에서 이 매개 변수의 유효성을 검사하지 않습니다.

htConsultCall

서비스 공급자가 이러한 호출을 만들어야 하는 경우 새 호출에 대한 TAPI 핸들입니다. 일부 전화 통신 환경에서는 통화를 전달하는 것이 전달되는 당사자와 상담하는 데 사용되는 상담 전화를 만드는 부작용이 있습니다. 이러한 환경에서 서비스 공급자는 새 상담 호출을 만들고 이 값을 저장하고 호출 시 이벤트를 보고하는 LINEEVENT 프로시저에 대한 모든 후속 호출에서 사용해야 합니다. 상담 호출이 생성되지 않은 경우 서비스 공급자가 이 값을 무시할 수 있습니다.

lphdConsultCall

호출에 대한 서비스 공급자의 식별자를 나타내는 HDRVCALL 에 대한 포인터입니다. 통화를 전달하는 것이 전달되는 당사자와 상담하는 데 사용되는 상담 통화를 만드는 부작용이 있는 전화 통신 환경에서 서비스 공급자는 이 절차가 반환되기 전에 이 위치를 통화 핸들로 채워야 합니다. 서비스 공급자는 이 절차에서 반환되기 전에 새 호출에 대한 콜백을 수행할 수 있습니다. 상담 호출이 생성되지 않은 경우 HDRVCALL은 NULL로 유지해야 합니다.

lpCallParams

LINECALLPARAMS 형식의 구조체에 대한 포인터입니다. lineForward가 전달 대상에 대한 호출을 설정해야 하는 경우가 아니면 이 포인터는 서비스 공급자에서 무시됩니다(lphdConsultCall이 반환되며 이 경우 lpCallParams는 선택 사항임). NULL인 경우 기본 호출 매개 변수가 사용됩니다. 그렇지 않으면 지정된 호출 매개 변수가 htConsultCall을 설정하는 데 사용됩니다.

반환 값

오류가 발생하면 dwRequestID 또는 오류 번호를 반환합니다. 함수가 성공하면 해당 ASYNC_COMPLETIONlResult 실제 매개 변수는 0이거나 오류가 발생할 경우 오류 번호입니다. 가능한 반환 값은 다음과 같습니다.

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

설명

지정된 정방향 목록 매개 변수에 잘못된 정보가 포함되어 있으면 서비스 공급자가 LINEERR_INVALPARAM 반환합니다.

서비스 공급자는 LINEERR_INVALADDRESS 반환하는 경우 전화를 걸지 않습니다.

서비스 공급자는 스위치에서 전달이 설정되지 않고 서비스 공급자가 요청을 수락했음을 나타내기 위해 이 함수에 성공을 반환합니다. 전달이 스위치에서 설정되도록 하기 위해 LINE_ADDRESSSTATE (전달) 메시지가 전송됩니다.

주소 또는 주소 전달은 이 함수가 다시 호출될 때까지 계속 적용됩니다. 가장 최근의 전달 목록은 적용된 모든 이전 전달 목록을 대체합니다. NULL 포인터를 lpForwardList로 지정하여 이 함수를 호출하는 경우 서비스 공급자는 해당 시간에 수행되는 전달을 취소해야 합니다. 전달 목록의 항목에 대해 NULL 대상 주소를 지정하면 작업은 "방해 금지" 역할을 합니다.

주소의 전달 상태 외부(예: 스위치의 관리 작업 또는 다른 스테이션의 사용자)에 의해 영향을 받을 수도 있습니다. 서비스 공급자가 이 상태 변경을 인식하지 못할 수 있으며 스위치에 알려진 전달 상태와 동기화되지 않을 수 있습니다. 공급자는 항상 true로 알고 있는 내용을 나타내야 하며, 그렇지 않으면 전달 상태를 알 수 없음을 나타내야 합니다.

서비스 공급자는 의심의 여지없이 주소의 전달 상태를 알 수 없으므로(즉, 알 수 없는 방식으로 전달되었거나 전달되지 않았을 수 있음) 새 전달 지침을 설정하지 않는 한 TSPI_lineForward 성공합니다. 즉, 전달이 적용되지 않는 한 번에 모든 전달이 취소되는 요청이 성공합니다. 이는 용서할 수 없는 것이 없기 때문입니다. 새 전달 지침 집합만 호출할 수 있습니다.

이 작업의 성공 또는 실패는 이전 전달 지침 집합에 따라 달라지지 않으며 다른 전달 지침을 설정할 때도 마찬가지입니다. 필요한 경우 공급자는 새 전달 지침을 설정하기 전에 "모든 것을 취소"해야 합니다. 아날로그 전화 통신 환경에서 시간이 걸릴 수 있으므로 공급자는 현재 전달을 새 전달과 비교하고 스위치에 대한 지침만 실행하여 최종 상태로 전환할 수 있습니다(변경되지 않은 전달은 영향을 받지 않음).

LINEFORWARDLIST에 dwNumEntries가 0으로 설정된 경우 TSPI_lineForward 호출하면 NULLlpForwardList 매개 변수를 제공하는 것과 동일한 효과가 있습니다. 현재 적용 중인 모든 전달을 취소합니다.

lphdConsultCall로 반환된 NULL 값은 TAPI가 서비스 공급자가 상담 전화를 만들었는지 여부를 결정하는 유일한 방법이기 때문에 서비스 공급자는 NULL을 호출 핸들로 사용할 수 없습니다.

이 함수는 호출 수명을 시작하기 위해 TSPI 모델을 따른다는 점에서 해당 TAPI 함수와 다릅니다. TAPI와 서비스 공급자는 서로 호출을 나타내는 불투명 핸들을 교환합니다. 또한 서비스 공급자는 이 절차에서 반환되기 전에 새 호출에 대한 콜백을 수행할 수 있습니다. 어떤 경우든 서비스 공급자는 일치하는 ASYNC_COMPLETION 성공을 보고할 때까지 반환된 핸들을 "아직 유효하지 않음"으로 처리해야 합니다. 즉, 새 호출에 대한 메시지를 실행하거나 메시지의 호출 수 또는 줄에 대한 데이터 구조 상태 포함해서는 안 됩니다.