Struttura LINEDEVCAPS (tapi.h)

Articolo
03/05/2024

La struttura LINEDEVCAPS descrive le funzionalità di un dispositivo linea. La funzione lineGetDevCaps e la funzione TSPI_lineGetDevCaps restituiscono la struttura LINEDEVCAPS .

Sintassi

typedef struct linedevcaps_tag {
  DWORD          dwTotalSize;
  DWORD          dwNeededSize;
  DWORD          dwUsedSize;
  DWORD          dwProviderInfoSize;
  DWORD          dwProviderInfoOffset;
  DWORD          dwSwitchInfoSize;
  DWORD          dwSwitchInfoOffset;
  DWORD          dwPermanentLineID;
  DWORD          dwLineNameSize;
  DWORD          dwLineNameOffset;
  DWORD          dwStringFormat;
  DWORD          dwAddressModes;
  DWORD          dwNumAddresses;
  DWORD          dwBearerModes;
  DWORD          dwMaxRate;
  DWORD          dwMediaModes;
  DWORD          dwGenerateToneModes;
  DWORD          dwGenerateToneMaxNumFreq;
  DWORD          dwGenerateDigitModes;
  DWORD          dwMonitorToneMaxNumFreq;
  DWORD          dwMonitorToneMaxNumEntries;
  DWORD          dwMonitorDigitModes;
  DWORD          dwGatherDigitsMinTimeout;
  DWORD          dwGatherDigitsMaxTimeout;
  DWORD          dwMedCtlDigitMaxListSize;
  DWORD          dwMedCtlMediaMaxListSize;
  DWORD          dwMedCtlToneMaxListSize;
  DWORD          dwMedCtlCallStateMaxListSize;
  DWORD          dwDevCapFlags;
  DWORD          dwMaxNumActiveCalls;
  DWORD          dwAnswerMode;
  DWORD          dwRingModes;
  DWORD          dwLineStates;
  DWORD          dwUUIAcceptSize;
  DWORD          dwUUIAnswerSize;
  DWORD          dwUUIMakeCallSize;
  DWORD          dwUUIDropSize;
  DWORD          dwUUISendUserUserInfoSize;
  DWORD          dwUUICallInfoSize;
  LINEDIALPARAMS MinDialParams;
  LINEDIALPARAMS MaxDialParams;
  LINEDIALPARAMS DefaultDialParams;
  DWORD          dwNumTerminals;
  DWORD          dwTerminalCapsSize;
  DWORD          dwTerminalCapsOffset;
  DWORD          dwTerminalTextEntrySize;
  DWORD          dwTerminalTextSize;
  DWORD          dwTerminalTextOffset;
  DWORD          dwDevSpecificSize;
  DWORD          dwDevSpecificOffset;
  DWORD          dwLineFeatures;
  DWORD          dwSettableDevStatus;
  DWORD          dwDeviceClassesSize;
  DWORD          dwDeviceClassesOffset;
  GUID           PermanentLineGuid;
  DWORD          dwAddressTypes;
  GUID           ProtocolGuid;
  DWORD          dwAvailableTracking;
} LINEDEVCAPS, *LPLINEDEVCAPS;

Members

dwTotalSize

Dimensioni totali allocate a questa struttura di dati, in byte.

dwNeededSize

Dimensioni necessarie per questa struttura di dati per contenere tutte le informazioni restituite, in byte.

dwUsedSize

Dimensioni della parte di questa struttura di dati che contiene informazioni utili, in byte.

dwProviderInfoSize

Dimensioni del campo con dimensioni variabili contenenti informazioni sul provider di servizi, in byte.

dwProviderInfoOffset

Offset dall'inizio della struttura alle informazioni del provider di servizi, in byte.

I membri dwProviderInfoSize e dwProviderInfoOffset sono destinati a fornire informazioni sull'hardware e/o sul software del provider, ad esempio il nome del fornitore e i numeri di versione di hardware e software. Queste informazioni possono essere utili quando un utente deve chiamare il servizio clienti con problemi relativi al provider.

dwSwitchInfoSize

Dimensioni del campo dispositivo con dimensioni variabili contenenti informazioni sul commutatore, in byte.

dwSwitchInfoOffset

Offset dall'inizio della struttura alle informazioni sull'opzione, in byte.

I membri dwSwitchInfoSize e dwSwitchInfoOffset sono destinati a fornire informazioni sul commutatore a cui è connesso il dispositivo line, ad esempio il produttore del commutatore, il nome del modello, la versione del software e così via. Queste informazioni possono essere utili quando un utente deve chiamare il servizio clienti con problemi relativi al passaggio.

dwPermanentLineID

Identificatore permanente in base al quale il dispositivo di riga è noto nella configurazione del sistema. Si tratta di un nome permanente per il dispositivo line. Questo nome permanente (anziché dwDeviceID) non cambia man mano che le righe vengono aggiunte o rimosse dal sistema e vengono mantenute tramite gli aggiornamenti del sistema operativo. Può quindi essere utilizzato per collegare informazioni specifiche della riga nei file di .ini (o altri file) in modo che non sia interessato dall'aggiunta o dalla rimozione di altre righe o modificando il sistema operativo.

dwLineNameSize

Dimensioni del campo dispositivo di dimensioni variabile contenente un nome configurabile dall'utente per questo dispositivo di riga, in byte.

dwLineNameOffset

Offset dall'inizio di questa struttura di dati al nome del dispositivo di riga. Questo nome può essere configurato dall'utente durante la configurazione del provider di servizi del dispositivo line e viene fornito per comodità dell'utente. Le dimensioni del campo sono specificate da dwLineNameSize.

dwStringFormat

Formato stringa usato con questo dispositivo di riga. Questo membro usa una delle costanti STRINGFORMAT_.

dwAddressModes

Modalità in base alla quale viene specificato l'indirizzo di origine. Questo membro usa le costanti LINEADDRESSMODE_.

dwNumAddresses

Numero di indirizzi associati a questo dispositivo di riga. I singoli indirizzi vengono indicati dagli identificatori di indirizzo. Gli identificatori di indirizzo variano da zero a uno minore del valore indicato da dwNumAddresses.

dwBearerModes

Matrice di flag che indica le diverse modalità di connessione che l'indirizzo è in grado di supportare. Questo membro utilizza una o più costanti LINEBEARERMODE_.

dwMaxRate

Frequenza massima dei dati per lo scambio di informazioni sulla chiamata, espressa in bit al secondo.

dwMediaModes

Matrice di flag che indica i diversi tipi di supporti che l'indirizzo è in grado di supportare. Questo membro utilizza una o più costanti LINEMEDIAMODE_.

dwGenerateToneModes

Toni che possono essere generati in questa riga. Questo membro utilizza una o più costanti LINETONEMODE_.

dwGenerateToneMaxNumFreq

Numero massimo di frequenze che è possibile specificare nella descrizione di un tono generale utilizzando la struttura di dati LINEGENERATETONE durante la generazione di un tono tramite lineGenerateTone. Il valore 0 indica che la generazione del tono non è disponibile.

dwGenerateDigitModes

Modalità cifre che possono essere generate in questa riga. Questo membro utilizza una o più costanti LINEDIGITMODE_.

dwMonitorToneMaxNumFreq

Numero massimo di frequenze che è possibile specificare nella descrizione di un tono generale utilizzando la struttura di dati LINEMONITORTONE durante il monitoraggio di un tono generale tramite lineMonitorTones. Il valore 0 indica che il monitoraggio del tono non è disponibile.

dwMonitorToneMaxNumEntries

Numero massimo di voci che è possibile specificare in un elenco di toni per lineMonitorTones.

dwMonitorDigitModes

Modalità cifre che possono essere rilevate in questa riga. Questo membro utilizza una o più costanti LINEDIGITMODE_.

dwGatherDigitsMinTimeout

Valore minimo che può essere specificato sia per i valori di timeout della prima cifra che per i valori di timeout tra cifre usati da lineGatherDigits, in millisecondi. Se sia dwGatherDigitsMinTimeout che dwGatherDigitsMaxTimeout sono zero, i timeout non sono supportati.

dwGatherDigitsMaxTimeout

Valore massimo che può essere specificato sia per i valori di timeout della prima cifra che per i valori di timeout tra cifre utilizzati da lineGatherDigits, in millisecondi. Se sia dwGatherDigitsMinTimeout che dwGatherDigitsMaxTimeout sono zero, i timeout non sono supportati.

dwMedCtlDigitMaxListSize

Numero massimo di voci che è possibile specificare nel parametro elenco cifre di lineSetMediaControl.

dwMedCtlMediaMaxListSize

Numero massimo di voci che è possibile specificare nel parametro dell'elenco multimediale di lineSetMediaControl.

dwMedCtlToneMaxListSize

Numero massimo di voci che è possibile specificare nel parametro dell'elenco toni di lineSetMediaControl.

dwMedCtlCallStateMaxListSize

Numero massimo di voci che è possibile specificare nel parametro dell'elenco di stati della chiamata di lineSetMediaControl.

dwDevCapFlags

Funzionalità di dispositivo booleane. Questo membro utilizza una o più costanti LINEDEVCAPFLAGS_.

dwMaxNumActiveCalls

Numero massimo di chiamate (larghezza di banda minima) che possono essere attive (connesse) sulla riga in qualsiasi momento. Il numero effettivo di chiamate attive può essere inferiore se sono state stabilite chiamate di larghezza di banda più elevate sulla riga.

dwAnswerMode

Effetto sulla chiamata attiva quando risponde a un'altra chiamata di offerta su un dispositivo line. Questo membro usa una delle costanti LINEANSWERMODE_.

dwRingModes

Numero di diverse modalità circolari che possono essere segnalate nel messaggio LINE_LINEDEVSTATE con l'indicazione dell'anello . Diverse modalità di anello variano da uno a dwRingModes. Zero indica che non esiste alcun anello.

dwLineStates

Componenti di stato riga diversi per i quali l'applicazione può ricevere una notifica in un messaggio di LINE_LINEDEVSTATE in questa riga. Questo membro utilizza una o più costanti LINEDEVSTATE_.

dwUUIAcceptSize

Dimensioni massime delle informazioni utente, incluso il terminatore Null , che possono essere inviate durante una chiamata accettata.

dwUUIAnswerSize

Dimensioni massime delle informazioni utente, incluso il carattere di terminazione Null , che possono essere inviate durante una risposta di chiamata.

dwUUIMakeCallSize

Dimensioni massime delle informazioni utente, incluso il terminatore Null , che possono essere inviate durante una chiamata.

dwUUIDropSize

Dimensioni massime delle informazioni utente, incluso il carattere di terminazione Null , che possono essere inviate durante un rilascio di chiamata.

dwUUISendUserUserInfoSize

Dimensioni massime delle informazioni utente, incluso il terminatore Null , che possono essere inviate separatamente in qualsiasi momento durante una chiamata con lineSendUserUserInfo.

dwUUICallInfoSize

Dimensioni massime delle informazioni utente, incluso il carattere di terminazione Null , che possono essere ricevute nella struttura LINECALLINFO .

MinDialParams

Valore minimo per i parametri di composizione che possono essere impostati per le chiamate in questa riga, in millisecondi. È possibile impostare i parametri di composizione sui valori nell'intervallo MinDialParams su MaxDialParams. La granularità delle impostazioni effettive è specifica del provider di servizi.

MaxDialParams

Valore massimo per i parametri di composizione che possono essere impostati per le chiamate in questa riga, in millisecondi. È possibile impostare i parametri di composizione sui valori nell'intervallo MinDialParams su MaxDialParams. La granularità delle impostazioni effettive è specifica del provider di servizi.

DefaultDialParams

Parametri di composizione predefiniti usati per le chiamate su questa riga. Questi valori di parametro possono essere sottoposti a override per ogni chiamata.

dwNumTerminals

Numero di terminali che possono essere impostati per questo dispositivo di riga, i relativi indirizzi o le relative chiamate. I singoli terminali sono indicati da ID terminale e variano da zero a uno minore del valore indicato da dwNumTerminals.

dwTerminalCapsSize

Dimensioni del campo dispositivo con dimensioni variabili contenenti una matrice con voci di tipo LINETERMCAPS, in byte.

dwTerminalCapsOffset

Offset dall'inizio di questa struttura al campo dispositivo con dimensioni variabili contenente una matrice con voci di tipo LINETERMCAPS. Questa matrice viene indicizzata in base agli ID del terminale, nell'intervallo compreso tra zero e dwNumTerminals meno uno. Ogni voce nella matrice specifica le funzionalità del dispositivo terminale del terminale corrispondente. Le dimensioni del campo sono specificate da dwTerminalCapsSize.

dwTerminalTextEntrySize

Dimensioni di ogni descrizione del testo del terminale, incluso il carattere di terminazione Null , a cui punta dwTerminalTextSize e dwTerminalTextOffset, in byte.

dwTerminalTextSize

Dimensioni del campo con dimensioni variabili contenenti testo descrittivo su ognuno dei terminali disponibili della riga, incluso il carattere di terminazione Null , in byte

dwTerminalTextOffset

Offset dall'inizio di questa struttura al testo descrittivo relativo a ognuno dei terminali disponibili della riga, in byte. Ogni messaggio è lungo byte dwTerminalTextEntrySize . Il formato stringa di queste descrizioni testuali è indicato da dwStringFormat nelle funzionalità del dispositivo della riga. Le dimensioni del campo sono specificate da dwTerminalTextSize.

dwDevSpecificSize

Dimensioni del campo specifico del dispositivo di dimensioni variabili, in byte. Se le informazioni specifiche del dispositivo sono un puntatore a una stringa, la dimensione deve includere il carattere di terminazione Null .

dwDevSpecificOffset

Offset dall'inizio di questa struttura al campo specifico del dispositivo, in byte. Le dimensioni del campo vengono specificate da dwDevSpecificSize.

dwLineFeatures

Funzionalità disponibili per questa riga usando le costanti LINEFEATURE_. Per richiamare una funzionalità supportata è necessario che la riga sia nello stato corretto e che il dispositivo linea sottostante venga aperto in modalità compatibile. Uno zero in una posizione di bit indica che la funzionalità corrispondente non è mai disponibile. Uno indica che la funzionalità corrispondente può essere disponibile se la riga è nello stato appropriato affinché l'operazione sia significativa. Questo membro consente a un'applicazione di individuare le funzionalità della riga che possono essere (e che non possono mai essere) supportate dal dispositivo.

dwSettableDevStatus

Valori LINEDEVSTATUSFLAGS che possono essere modificati usando lineSetLineDevStatus.

dwDeviceClassesSize

Dimensioni di una stringa contenente gli identificatori di classe del dispositivo supportati in uno o più indirizzi in questa riga, incluso il carattere di terminazione Null , in byte.

dwDeviceClassesOffset

Offset dall'inizio di questa struttura a una stringa contenente gli identificatori di classe del dispositivo supportati in uno o più indirizzi in byte in questa riga. Queste stringhe sono destinate all'uso con lineGetID; sono separati da NULLs e l'ultimo identificatore nell'elenco è seguito da due valori NULL. Le dimensioni del campo sono specificate da dwDeviceClassesSize.

PermanentLineGuid

GUID associato in modo permanente al dispositivo della riga.

dwAddressTypes

Tipo di indirizzo utilizzato per la chiamata. Questo membro della struttura è disponibile solo se la versione TAPI negoziata è 3.0 o successiva.

ProtocolGuid

Protocollo TAPI corrente. Questo membro della struttura è disponibile solo se la versione TAPI negoziata è 3.0 o successiva. I protocolli vengono dichiarati in tapi3.h.

dwAvailableTracking

Rilevamento disponibile, rappresentato da una costante LINECALLHUBTRACKING.constant. Questo membro della struttura è disponibile solo se la versione TAPI negoziata è 3.0 o successiva.

Commenti

Le estensioni specifiche del dispositivo devono usare l'area di dimensioni variabili DevSpecific (dwDevSpecificSize e dwDevSpecificOffset) di questa struttura di dati.

Le applicazioni meno recenti vengono compilate senza nuovi membri nella struttura LINEDEVCAPS e usano sizeOF LINEDEVCAPS inferiori alle nuove dimensioni. L'applicazione passa un parametro dwAPIVersion con la funzione lineGetDevCaps , che può essere usata per indicazioni da TAPI nella gestione di questa situazione. Se l'applicazione passa un membro dwTotalSize minore della dimensione della parte fissa della struttura, come definito nella dwAPIVersion specificata, viene restituito LINEERR_STRUCTURETOOSMALL. Se è stata allocata memoria sufficiente dall'applicazione, prima di chiamare TSPI_lineGetDevCaps, TAPI imposta i membri dwNeededSize e dwUsedSize sulle dimensioni fisse della struttura come esiste nella versione dell'API specificata.

Le nuove applicazioni devono essere riconosciute della versione dell'API negoziata e non esaminare il contenuto dei membri nella parte fissa oltre la fine originale della parte fissa della struttura per la versione dell'API negoziata.

Se il bit LINEBEARERMODE_DATA è impostato nel membro dwBearerModes , il membro dwMaxRate indica la velocità massima di trasmissione digitale sul canale di connessione. Il membro dwMaxRate della struttura LINEDEVCAPS può contenere valori validi anche se il membro dwBearerModes della struttura LINEDEVCAPS non è impostato su LINEBEARERMODE_DATA.

Se LINEBEARERMODE_DATA non è impostato in dwBearerModes, ma il valore LINEBEARERMODE_VOICE è impostato e il valore LINEMEDIAMODE_DATAMODEM viene impostato nel membro dwMediaModes , il membro dwMaxRate indica la velocità massima di bit SYNCHRONOUS (DCE) sulla linea telefonica per il modem collegato o equivalente funzionale. Ad esempio, se la velocità di modularità più veloce del modem è V.32bis a 14.400bps, dwMaxRate è uguale a 14400. Questa non è la velocità di porta DTE più veloce (che probabilmente sarebbe 38400, 57600 o 115200), ma la velocità di bit più veloce supportata dal modem sulla linea telefonica.

L'applicazione deve prestare attenzione a verificare che LINEBEARERMODE_DATA non sia impostata, per evitare l'errata interpretazione del membro dwMaxRate . È probabile che sia 64000 o superiore se è impostato LINEBEARERMODE_DATA.

Va inoltre notato che se il modem non è stato identificato in modo specifico (ad esempio, si tratta di un modem "generico"), la figura indicata è una "migliore ipotesi" in base all'esame del modem.

I membri dwSettableDevStatus tramite dwDeviceClassesOffset sono disponibili solo per le applicazioni che aprono il dispositivo line con una versione TAPI 2.0 o successiva.