Funzione lineDrop (tapi.h)

Articolo
08/26/2023

La funzione lineDrop elimina o disconnette la chiamata specificata. L'applicazione ha la possibilità di specificare le informazioni utente da trasmettere come parte della disconnessione della chiamata.

Sintassi

LONG lineDrop(
  HCALL  hCall,
  LPCSTR lpsUserUserInfo,
  DWORD  dwSize
);

Parametri

hCall

Handle per la chiamata da eliminare. L'applicazione deve essere un proprietario della chiamata. Lo stato della chiamata di hCall può essere qualsiasi stato, ad eccezione dell'inattività.

lpsUserUserInfo

Puntatore a una stringa contenente le informazioni utente da inviare all'entità remota come parte della disconnessione della chiamata. Questo puntatore può essere lasciato NULL se non devono essere inviate informazioni utente.This pointer can be left NULL if no user-user information is to be sent. Le informazioni utente vengono inviate solo se supportate dalla rete sottostante (vedere LINEDEVCAPS). Il campo discriminatorio del protocollo per le informazioni utente-utente, se necessario, deve essere visualizzato come primo byte del buffer a cui punta lpsUserUserInfo e deve essere tenuto conto di in dwSize.

dwSize

Dimensioni in byte delle informazioni utente-utente in lpsUserUserInfo. Se lpsUserUserInfo è NULL, all'entità chiamante non vengono inviate informazioni sull'utente e dwSize viene ignorata.

Valore restituito

Restituisce un identificatore di richiesta positivo se la funzione viene completata in modo asincrono o un numero di errore negativo se si verifica un errore. Il parametro dwParam2 del messaggio di LINE_REPLY corrispondente è zero se la funzione ha esito positivo o è un numero di errore negativo se si verifica un errore. I valori restituiti possibili sono:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM, LINEERR_OPERATIONFAILED, LINEERR_NOTOWNER, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_USERUSERINFOTOOBIG, LINEERR_INVALCALLSTATE, LINEERR_UNINITIALIZED.

Commenti

Quando si richiama lineDrop, anche le chiamate correlate possono essere interessate. Ad esempio, l'eliminazione di una conferenza telefonica può eliminare tutte le singole chiamate partecipanti. LINE_CALLSTATE messaggi vengono inviati all'applicazione per tutte le chiamate il cui stato di chiamata è interessato. Una chiamata eliminata passa in genere allo stato di inattività . Richiamare lineDrop su una chiamata nello stato dell'offerta rifiuta la chiamata. Non tutte le reti telefoniche offrono questa funzionalità.

Una chiamata nello stato onholdpending viene in genere ripristinata allo stato connesso . Quando si elimina la chiamata di consultazione alla terza parte per una conferenza telefonica o quando si rimuove la terza parte in una conferenza telefonica stabilita in precedenza, il provider (e il commutatore) può rilasciare il bridge di conferenza e ripristinare la chiamata a una normale chiamata a due parti. In questo caso, hConfCall passa allo stato di inattività e l'unica chiamata partecipante rimanente passa allo stato connesso . Alcune opzioni "annullano" automaticamente l'altra chiamata.

L'applicazione ha la possibilità di inviare informazioni utente-utente al momento dell'eliminazione. Anche se è possibile inviare informazioni sull'utente, non vi è alcuna garanzia che la rete fornirà queste informazioni all'entità remota.

In varie configurazioni bridged o party-line quando più parti sono sulla chiamata, lineDrop potrebbe non cancellare effettivamente la chiamata. Ad esempio, in una situazione bridged, un'operazione lineDrop potrebbe non rilasciare effettivamente la chiamata perché lo stato di altre stazioni sulla chiamata può governare; In alternativa, la chiamata può essere semplicemente modificata alla modalità LINECONNECTEDMODE_INACTIVE se rimane collegata ad altre stazioni.