Функция TSPI_lineForward (tspi.h)

Статья
08/26/2023

Функция 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 или номер ошибки при возникновении ошибки. Фактический параметр lResult соответствующего ASYNC_COMPLETION равен нулю при успешном выполнении функции или номеру ошибки при возникновении ошибки. Возможные возвращаемые значения:

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

Поставщик услуг возвращает эту функцию успешно, чтобы указать только, что запрос принят поставщиком услуг, а не на то, что переадресация настроена на коммутаторе. Отправляется сообщение LINE_ADDRESSSTATE (пересылка), указывающее, что переадресация настроена на коммутаторе.

Переадресация адреса или адресов остается в силе до тех пор, пока эта функция не будет вызвана снова. Последний список переадресации заменяет любой старый. Если эта функция вызывается, указывая указатель NULL как lpForwardList, поставщик услуг должен отменить любую пересылку, которая выполняется в это время. Если для записи в списке переадресации указан конечный адрес NULL , операция действует как "do-not-disturb".

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

Так как поставщик услуг может не знать состояние пересылки адреса без каких-либо сомнений (т. е. он мог быть переадресован или не перенаправлен неизвестным способом), TSPI_lineForward выполняется успешно, если не удается задать новые инструкции переадресации. Иными словами, запрос на отмену всех переадресации в то время, когда переадресация отсутствует, завершается успешно. Это связано с тем, что нет непредугодных; Можно вызвать только новый набор инструкций переадресации.

Успех или сбой этой операции не зависит от предыдущего набора инструкций переадресации, и то же самое верно при настройке различных инструкций переадресации. При необходимости поставщик должен "отменить все" перед настройкой новых инструкций переадресации. Так как в средах аналоговой телефонии это может занять много времени, поставщику также может потребоваться сравнить текущую пересылку с новой и выпустить инструкции для коммутатора, чтобы перейти в конечное состояние (не изменив перенаправление без изменений).

Вызов TSPI_lineForward, если параметр LINEFORWARDLIST имеет значение 0 в параметре dwNumEntries, имеет тот же эффект, что и параметр lpForwardListNULL; он отменяет все переадресации, действующие в настоящее время.

Так как значение NULL , возвращаемое в lphdConsultCall , является единственным способом для TAPI определить, создал ли поставщик услуг консультационный звонок, поставщик услуг не может использовать NULL в качестве дескриптора вызова.

Эта функция отличается от соответствующей функции TAPI тем, что она следует модели TSPI для начала времени существования вызова. TAPI и поставщик услуг обмениваются непрозрачными дескрипторами, представляющими вызов друг с другом. Кроме того, поставщик услуг может выполнять обратные вызовы для нового вызова, прежде чем он возвратится из этой процедуры. В любом случае поставщик услуг также должен считать возвращенный дескриптор "еще недействителен" до тех пор, пока соответствующий ASYNC_COMPLETION не сообщит об успешном выполнении. Иными словами, он не должен выдавать сообщения для нового вызова или включать их в число вызовов в сообщениях или структурах данных о состоянии для строки.