Leggere in inglese

Condividi tramite


Funzione lineOpenW (tapi.h)

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

Sintassi

LONG lineOpenW(
  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 della riga 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 della 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 richiama altre funzioni nel dispositivo a riga aperta.

dwAPIVersion

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

dwExtVersion

Numero di versione dell'estensione in 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 vengono passati all'applicazione con ogni messaggio associato a questa riga o a indirizzi o chiamate su questa riga. Questo parametro non viene interpretato dall'API Telefonia.

dwPrivileges

Privilegi che l'applicazione vuole quando viene notificata 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 è specificato, ma lpCallParams non è valido o l'id dwAddressID incluso non esiste nella riga, l'apertura non riesce 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 della proprietà iniziale delle chiamate create dal provider di servizi usando un messaggio di LINE_NEWCALL . Un'applicazione che apre la riga con LINECALLPRIVILEGE_MONITOR continua a ricevere handle di monitoraggio per tutte le chiamate create nella riga. Inoltre, l'applicazione non è limitata in alcun modo a effettuare chiamate o eseguire altre operazioni che influiscono su altri indirizzi nella riga aperta.

Quando viene specificata l'opzione LINEOPENOPTION_PROXY (solo TAPI 2.0 o versione successiva), l'applicazione deve anche indicare quali richieste proxy specifiche vengono gestite. Lo fa passando, nel parametro lpCallParams, un puntatore a una struttura LINECALLPARAMS in cui sono stati impostati i membri dwDevSpecificSize e dwDevSpecificOffset 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 le cinque funzioni correlate all'agente passerebbe in una matrice di cinque DWORDs (dwDevSpecificSize sarebbe 20 decimale) contenente i cinque valori definiti LINEPROXYREQUEST_.

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

Tentativi successivi, dalla stessa applicazione o altre applicazioni, di aprire il dispositivo della riga e registrare per gestire le stesse richieste proxy di un'applicazione già registrata con LINEERR_NOTREGISTERED.

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

Altre combinazioni di flag restituiscono l'errore di 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 chiamare 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 usato solo se viene usato LINEMAPPER o LINEOPENOPTION_PROXY; in caso contrario , lpCallParams viene ignorato. Descrive il parametro di chiamata che il dispositivo di riga deve essere in grado di fornire.

Valore restituito

Restituisce zero se la richiesta ha esito positivo o un numero di errore 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 LINEERR_ALLOCATED viene restituito, 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 LINEERR_RESOURCEUNAVAIL viene restituito, la riga non può essere aperta a causa di un overcommitment di risorse dinamico, ad esempio in cicli di processore DSP o memoria. Questo overcommitment può essere transitorio, causato dal monitoraggio del tipo di supporto o toni, e le modifiche in queste attività da altre applicazioni possono rendere possibile riaprire la riga entro un breve periodo di tempo. Se LINEERR_REINIT viene restituito e la reinizializzazione TAPI è stata richiesta (ad esempio, come risultato dell'aggiunta o rimozione di un provider di servizi di telefonia), le richieste lineOpen vengono rifiutate con questo errore finché l'ultima applicazione non arresta l'utilizzo dell'API (usando lineShutdown); in quel momento la nuova configurazione diventa effettiva e le applicazioni possono ancora una volta chiamare lineInitializeEx.

L'apertura di una riga consente sempre all'applicazione di effettuare chiamate su qualsiasi indirizzo disponibile nella riga. La possibilità dell'applicazione di gestire le chiamate in ingresso o di essere la destinazione dei call handoff sulla riga è determinata dal parametro dwMediaModes . La funzione lineOpen registra l'applicazione come 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 chiamate non classificate (chiamate di tipo multimediale sconosciuto), può specificare LINECALLPRIVILEGE_OWNER e LINEMEDIAMODE_UNKNOWN. In caso contrario, l'applicazione deve specificare il tipo di supporto interessato alla gestione. L'applicazione può chiamare la funzione lineSetCallPrivilege per modificare i privilegi di chiamata specificati dalla LINECALLPRIVILEGES_Constants.

I tipi di supporto specificati con lineOpen aggiungono al valore predefinito per il monitoraggio del tipo di supporto del provider per la determinazione del tipo di chiamata in ingresso iniziale. La funzione lineMonitorMedia modifica la maschera che controlla i messaggi di LINE_MONITORMEDIA . 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 chiamate usando lineMakeCall, lineUnpark, linePickup e lineSetupConference (con un 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 quando arriva prima una chiamata in ingresso o quando viene consegnata una chiamata. La funzione lineHandoff viene chiamata per distribuire la proprietà di una chiamata a un'altra applicazione. Se l'utente non assegna priorità all'applicazione e più applicazioni aprono lo stesso dispositivo linea, per impostazione predefinita, l'applicazione denominata 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 vuole, può chiamare lineGetNewCalls per ottenere handle a queste chiamate.

Un'applicazione che gestisce la voce automatizzata deve anche selezionare la modalità di apertura vocale interattiva e essere assegnata 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 riuscirebbero a raggiungere l'applicazione vocale automatizzata e verranno eliminate.

La stessa applicazione, o istanze diverse della stessa applicazione, può aprire la stessa riga più volte con gli stessi parametri o 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 ottenuti con lineNegotiateAPIVersion e lineNegotiateExtVersion. Il numero di versioni consente la combinazione e la corrispondenza di diverse versioni dell'applicazione con versioni diverse dell'API e versioni del provider di servizi.

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

Nota

L'intestazione tapi.h definisce lineOpen come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

Requisito Valore
Piattaforma di destinazione Windows
Intestazione tapi.h
Libreria Tapi32.lib
DLL Tapi32.dll

Vedi anche

Informazioni di riferimento sui servizi di telefonia di base

LINECALLPARAMS

LINE_CALLSTATE

LINE_MONITORMEDIA

LINE_PROXYREQUEST

Panoramica dei riferimenti a TAPI 2.2

lineClose

lineForward

lineGetConfRelatedCalls

lineGetID

lineGetNewCalls

lineInitializeEx

lineMakeCall

lineMonitorMedia

lineNegotiateAPIVersion

lineNegotiateExtVersion

linePickup

lineProxyMessage

lineProxyResponse

lineSetupConference

lineShutdown

lineUnpark