Funzione lineOpen (tapi.h)

Articolo
03/05/2024

La funzione lineOpen apre il dispositivo linea specificato dall'identificatore del dispositivo e restituisce un handle di riga per il dispositivo linea aperto corrispondente. Questo handle di riga viene usato nelle operazioni successive sul dispositivo line.

Sintassi

LONG lineOpen(
  HLINEAPP               hLineApp,
  DWORD                  dwDeviceID,
  LPHLINE                lphLine,
  DWORD                  dwAPIVersion,
  DWORD                  dwExtVersion,
  DWORD_PTR              dwCallbackInstance,
  DWORD                  dwPrivileges,
  DWORD                  dwMediaModes,
  LPLINECALLPARAMS const lpCallParams
);

Parametri

hLineApp

Gestire la registrazione dell'applicazione con TAPI.

dwDeviceID

Identifica il dispositivo linea da aprire. Può essere un identificatore di dispositivo valido o il valore.

Valore	Significato
LINEMAPPER	Questo valore viene usato per aprire un dispositivo linea nel sistema che supporta le proprietà specificate in lpCallParams. L'applicazione può usare lineGetID per determinare l'identificatore del dispositivo di riga aperto.

lphLine

Puntatore a un handle HLINE che viene quindi caricato con l'handle che rappresenta il dispositivo linea aperto. Usare questo handle per identificare il dispositivo quando si richiamano altre funzioni nel dispositivo a riga aperta.

dwAPIVersion

Numero di versione dell'API con cui l'applicazione e l'API di telefonia hanno accettato di funzionare. Questo numero viene ottenuto con lineNegotiateAPIVersion.

dwExtVersion

Numero di versione dell'estensione con cui l'applicazione e il provider di servizi accettano di funzionare. Questo numero è zero se l'applicazione non usa estensioni. Questo numero viene ottenuto con lineNegotiateExtVersion.

dwCallbackInstance

I dati dell'istanza utente passati all'applicazione con ogni messaggio associato a questa riga o con indirizzi o chiamate su questa riga. Questo parametro non viene interpretato dall'API Di telefonia.

dwPrivileges

Privilegi che l'applicazione vuole ricevere una notifica per una chiamata Questo parametro contiene una o più costanti LINECALLPRIVILEGE_. Per le applicazioni che usano TAPI versione 2.0 o successiva, i valori per questo parametro possono essere combinati anche con una o più costanti LINEOPENOPTION_.

Se viene specificata l'opzione LINEOPENOPTION_SINGLEADDRESS, l'applicazione è interessata solo alle nuove chiamate visualizzate nell'indirizzo specificato dal membro dwAddressID nella struttura LINECALLPARAMS a cui punta il parametro lpCallParams (che deve essere specificato).

Se LINEOPENOPTION_SINGLEADDRESS viene specificato ma lpCallParams non è valido o il valore dwAddressID incluso non esiste nella riga, l'apertura ha esito negativo con LINERR_INVALADDRESSID.

Oltre a impostare il membro dwAddressID della struttura LINECALLPARAMS sull'indirizzo desiderato, l'applicazione deve anche impostare dwAddressMode in LINECALLPARAMS su LINEADDRESSMODE_ADDRESSID.

L'opzione LINEOPENOPTION_SINGLEADDRESS influisce solo sull'assegnazione TAPI della proprietà iniziale delle chiamate create dal provider di servizi tramite un messaggio di LINE_NEWCALL . Un'applicazione che apre la riga con LINECALLPRIVILEGE_MONITOR continua a ricevere handle di monitoraggio a tutte le chiamate create nella riga. Inoltre, l'applicazione non è limitata in alcun modo dall'effettuare chiamate o eseguire altre operazioni che influiscono su altri indirizzi sulla riga aperta.

Quando viene specificata l'opzione LINEOPENOPTION_PROXY (solo TAPI 2.0 o versione successiva), l'applicazione deve indicare anche quali richieste proxy specifiche sono pronte a gestire. Lo fa passando, nel parametro lpCallParams , un puntatore a una struttura LINECALLPARAMS in cui i membri dwDevSpecificSize e dwDevSpecificOffset sono stati impostati per delimitare una matrice di DWORDs. Ogni elemento di questa matrice deve contenere una delle costanti LINEPROXYREQUEST_. Ad esempio, un'applicazione del gestore proxy che supporta tutte e cinque le funzioni correlate all'agente passerebbe una matrice di cinque DWORDs (dwDevSpecificSize sarebbe 20 decimale) contenente i cinque valori definiti LINEPROXYREQUEST_.

L'applicazione del gestore di richieste proxy può essere eseguita in qualsiasi computer che dispone dell'autorizzazione per controllare il dispositivo della riga. Tuttavia, le richieste vengono sempre instradate attraverso il server in cui viene eseguito il provider di servizi che controlla effettivamente il dispositivo linea. Pertanto, è più efficiente se l'applicazione che gestisce le richieste proxy (ad esempio il controllo agente ACD) viene eseguita direttamente sul server insieme al provider di servizi.

I tentativi successivi, da parte della stessa applicazione o di altre applicazioni, di aprire il dispositivo line e registrarsi per gestire le stesse richieste proxy di un'applicazione già registrata hanno esito negativo con LINEERR_NOTREGISTERED.

Per interrompere la gestione delle richieste nella riga, l'applicazione chiama semplicemente lineClose.

Altre combinazioni di flag restituiscono l'errore LINEERR_INVALPRIVSELECT.

dwMediaModes

Tipo di supporto o modalità di interesse per l'applicazione. Questo parametro viene usato per registrare l'applicazione come destinazione potenziale per la chiamata in ingresso e il call handoff per il tipo di supporto specificato. Questo parametro è significativo solo se il bit LINECALLPRIVILEGE_OWNER in dwPrivileges è impostato (e ignorato in caso contrario). Questo parametro usa una o più costanti LINEMEDIAMODE_.

lpCallParams

Puntatore a una struttura di tipo LINECALLPARAMS. Questo puntatore viene utilizzato solo se viene utilizzato LINEMAPPER o LINEOPENOPTION_PROXY; in caso contrario , lpCallParams viene ignorato. Descrive il parametro di chiamata che il dispositivo linea deve essere in grado di fornire.

Valore restituito

Restituisce zero se la richiesta ha esito positivo o negativo se si verifica un errore. I valori restituiti possibili sono:

LINEERR_ALLOCATED, LINEERR_LINEMAPPERFAILED, LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_INVALPRIVSELECT, LINEERR_REINIT, LINEERR_NODEVICE, LINEERR_OPERATIONUNAVAIL.

Commenti

Se viene restituito LINEERR_ALLOCATED, la riga non può essere aperta a causa di una condizione "persistente", ad esempio quella di una porta seriale aperta esclusivamente da un altro processo. Se viene restituito LINEERR_RESOURCEUNAVAIL, la riga non può essere aperta a causa di un overcommit di risorse dinamiche, ad esempio nei cicli del processore DSP o nella memoria. Questo overcommitment può essere transitorio, causato dal monitoraggio del tipo di supporto o toni, e le modifiche apportate a queste attività da altre applicazioni possono consentire di riaprire la riga entro un breve periodo di tempo. Se viene restituito LINEERR_REINIT e la reinizializzazione TAPI è stata richiesta (ad esempio, in seguito all'aggiunta o alla rimozione di un provider di servizi di telefonia), le richieste lineOpen vengono rifiutate con questo errore fino a quando l'ultima applicazione non arresta l'utilizzo dell'API (tramite lineShutdown); in quel momento la nuova configurazione diventa effettiva e le applicazioni sono nuovamente autorizzate a chiamare lineInitializeEx.

L'apertura di una riga autorizza sempre l'applicazione a effettuare chiamate su qualsiasi indirizzo disponibile nella riga. La possibilità dell'applicazione di gestire le chiamate in ingresso o di essere la destinazione degli handoff di chiamata sulla riga è determinata dal parametro dwMediaModes . La funzione lineOpen registra l'applicazione come un interesse per il monitoraggio delle chiamate o la ricezione della proprietà delle chiamate che sono dei tipi di supporti specificati. Se l'applicazione vuole solo monitorare le chiamate, può specificare LINECALLPRIVILEGE_MONITOR. Se l'applicazione vuole solo effettuare chiamate in uscita, può specificare LINECALLPRIVILEGE_NONE. Se l'applicazione è disposta a controllare le chiamate non classificate (chiamate di tipo supporto sconosciuto), può specificare LINECALLPRIVILEGE_OWNER e LINEMEDIAMODE_UNKNOWN. In caso contrario, l'applicazione deve specificare il tipo di supporto a cui è interessato la gestione. L'applicazione può chiamare la funzione lineSetCallPrivilege per modificare i privilegi di chiamata specificati dal LINECALLPRIVILEGES_Constants.

I tipi di supporti specificati con lineOpen aggiungono al valore predefinito per il monitoraggio del tipo di supporto del provider per la determinazione iniziale del tipo di chiamata in ingresso. La funzione lineMonitorMedia modifica la maschera che controlla LINE_MONITORMEDIA messaggi. Se un dispositivo linea viene aperto con privilegi di proprietario e un tipo di supporto di estensione non è registrato, viene restituito l'errore LINEERR_INVALMEDIAMODE.

Un'applicazione che ha aperto correttamente un dispositivo line può sempre avviare le chiamate usando lineMakeCall, lineUnpark, linePickup e lineSetupConference (con un valore hCallNULL), nonché usare lineForward (presupponendo che questa operazione sia consentita dalle funzionalità del dispositivo, dallo stato della riga e così via).

Una singola applicazione può specificare più flag contemporaneamente per gestire più tipi di supporti. I conflitti possono verificarsi se più applicazioni aprono lo stesso dispositivo linea per lo stesso tipo di supporto. Questi conflitti vengono risolti da uno schema di priorità in cui l'utente assegna priorità relative alle applicazioni. Gli utenti possono impostare le priorità dell'applicazione chiamando la funzione lineSetAppPriority . Solo l'applicazione con priorità più alta per un determinato tipo di supporto riceverà la proprietà (non richiesta) di una chiamata di tale tipo di supporto. La proprietà può essere ricevuta al primo arrivo di una chiamata in arrivo o quando viene consegnata una chiamata. La funzione lineHandoff viene chiamata per consegnare la proprietà di una chiamata a un'altra applicazione. Se l'utente non assegna priorità all'applicazione e più applicazioni aprono lo stesso dispositivo line, per impostazione predefinita, l'applicazione che ha chiamato lineOpen avrà la priorità più alta.

Qualsiasi applicazione (inclusa qualsiasi applicazione con priorità inferiore) può sempre acquisire la proprietà con lineGetNewCalls o lineGetConfRelatedCalls. Se un'applicazione apre una riga per il monitoraggio alla volta che le chiamate esistono nella riga, LINE_CALLSTATE messaggi per tali chiamate esistenti non vengono generati automaticamente alla nuova applicazione di monitoraggio. L'applicazione può eseguire una query sul numero di chiamate correnti sulla riga per determinare il numero di chiamate esistenti e, se lo desidera, può chiamare lineGetNewCalls per ottenere handle a queste chiamate.

Un'applicazione che gestisce la voce automatica deve anche selezionare la modalità interattiva di apertura della voce e avere la priorità più bassa per la voce interattiva. Il motivo è che i provider di servizi segnalano tutti i tipi di supporti vocali come voce interattiva. Se la determinazione del tipo di supporto non viene eseguita dall'applicazione per il tipo di supporto UNKNOWN e non è stata aperta alcuna applicazione vocale interattiva, le chiamate vocali non saranno in grado di raggiungere l'applicazione vocale automatizzata e verrebbero eliminate.

La stessa applicazione o istanze diverse della stessa applicazione può aprire più volte la stessa riga con gli stessi parametri o parametri diversi.

Quando un'applicazione apre un dispositivo line deve specificare la versione dell'API negoziata e, se vuole usare le estensioni della riga, deve specificare la versione dell'estensione specifica del dispositivo della riga. Questi numeri di versione devono essere stati ottenuti con lineNegotiateAPIVersion e lineNegotiateExtVersion. La numerazione delle versioni consente la combinazione e la corrispondenza di diverse versioni dell'applicazione con versioni api diverse e versioni del provider di servizi.

LINEMAPPER consente a un'applicazione di selezionare indirettamente una riga, tramite i servizi desiderati. Quando si apre un dispositivo line con LINEMAPPER, è vero quanto segue: tutti i membri dall'inizio della struttura dei dati LINECALLPARAMS tramite dwAddressMode sono rilevanti. Se dwAddressMode è LINEADDRESSMODE_ADDRESSID significa che qualsiasi indirizzo nella riga è accettabile, in caso contrario , se dwAddressMode è LINEADDRESSMODE_DIALABLEADDR, indicando che viene cercato un indirizzo di origine specifico (numero di telefono) o se si tratta di un'estensione specifica del provider, dwOrigAddressSize/Offset e la parte della parte della variabile a cui fanno riferimento sono rilevanti anche. Se dwAddressMode è un'estensione specifica del provider, le informazioni aggiuntive possono essere contenute nel membro di dimensione variabile dwDeviceSpecific .