funzione phoneGetIcon (tapi.h)

Articolo
03/05/2024

La funzione phoneGetIcon consente a un'applicazione di recuperare un'icona specifica del dispositivo del servizio (o specifica del provider) che può essere visualizzata all'utente.

Sintassi

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

Parametri

dwDeviceID

Identificatore del dispositivo telefonico l'icona richiesta.

lpszDeviceClass

Puntatore a una stringa con terminazione null che identifica un nome della classe di 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, in tal caso l'icona di livello più alto associata al dispositivo telefonico anziché un dispositivo di flusso multimediale specificato verrà selezionato.

lphIcon

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

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:

PHONEERR_BADDEVICEID, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_OPERATIONFAILED, PHONEERR_INVALDEVICECLASS, PHONEERR_UNINITIALIZED, PHONEERR_NOMEM, PHONEERR_NODEVICE.

Commenti

La funzione phoneGetIcon causa la restituzione di un handle (in lphIcon) a una risorsa icona (ottenuta da LoadIcon) associata al telefono specificato. 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 l'apertura del telefono.

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 phoneGetID. Ad esempio, se il telefono supporta l'API Comm, passando "COMM" come lpszDeviceClass , il provider restituisce un'icona correlata in particolare alle funzioni del dispositivo Comm del provider di servizi. I parametri "tapi/phone", "" o NULL possono essere usati per richiedere l'icona per il servizio telefonico.

Per le applicazioni che usano una versione TAPI precedente alla versione 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 del dispositivo telefono telefonico generico. Per le applicazioni che usano TAPI versione 2.0 o successiva, TAPI sostituisce l'icona del telefono predefinita solo se il parametro lpszDeviceClass è "tapi/phone", "" o NULL. Per qualsiasi altra classe di dispositivo, se la classe del dispositivo specificata non è valida o il provider non supporta le icone per la classe, phoneGetIcon restituisce PHONEERR_INVALDEVICECLASS.