Funzione lineGetIcon (tapi.h)

Articolo
03/08/2023

La funzione lineGetIcon consente a un'applicazione di recuperare un'icona specifica del dispositivo della riga di servizio (o specifica del provider) per la visualizzazione all'utente.

Sintassi

LONG lineGetIcon(
  DWORD   dwDeviceID,
  LPCSTR  lpszDeviceClass,
  LPHICON lphIcon
);

Parametri

dwDeviceID

Identificatore del dispositivo linea di cui è richiesta l'icona.

lpszDeviceClass

Puntatore a una stringa con terminazione Null che identifica un nome di classe del dispositivo. Questa classe di dispositivo consente all'applicazione di selezionare un'icona secondaria specifica applicabile a tale classe di dispositivo. Questo parametro è facoltativo e può essere lasciato NULL o vuoto, nel qual caso verrà selezionata l'icona di livello più alto associata al dispositivo line anziché un dispositivo di flusso multimediale specificato.

lphIcon

Puntatore a una posizione di memoria in cui viene restituito l'handle per l'icona.

Valore restituito

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

LINEERR_BADDEVICEID, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALDEVICECLASS, LINEERR_UNINITIALIZED, LINEERR_NOMEM, LINEERR_NODEVICE.

Commenti

La funzione lineGetIcon fa sì che il provider restituisca un handle (in lphIcon) a una risorsa icona (ottenuta da LoadIcon) associata alla riga specificata. L'handle dell'icona è per una risorsa associata al provider. L'applicazione deve usare CopyIcon se vuole fare riferimento all'icona dopo il caricamento del provider, che è improbabile che si verifichi finché l'applicazione ha la riga aperta.

Il parametro lpszDeviceClass consente al provider di restituire icone diverse in base al tipo di servizio a cui fa riferimento il chiamante. Le stringhe consentite sono uguali a per lineGetID. Ad esempio, se la riga supporta l'API Comm, il passaggio di "COMM" come lpszDeviceClass fa sì che il provider restituisca un'icona correlata in modo specifico alle funzioni del dispositivo Comm del provider di servizi. I parametri "tapi/line", "" o NULL possono essere usati per richiedere l'icona per il servizio di riga.

Per le applicazioni che usano una versione API precedente alla 2.0, se il provider non restituisce un'icona (se la classe di dispositivo specificata non è valida o il provider non supporta le icone), TAPI sostituisce un'icona generica del dispositivo della linea di telefonia. Per le applicazioni che usano l'API versione 2.0 o successiva, TAPI sostituisce l'icona a riga predefinita solo se il parametro lpszDeviceClass è "tapi/line", "" o NULL. Per qualsiasi altra classe di dispositivo, se la classe di dispositivo specificata non è valida o il provider non supporta le icone per la classe, lineGetIcon restituisce LINEERR_INVALDEVICECLASS.