phoneGetIcon-Funktion (tapi.h)

Artikel
08/26/2023

Die phoneGetIcon-Funktion ermöglicht es einer Anwendung, ein gerätespezifisches (oder anbieterspezifisches) Diensttelefonsymbol abzurufen, das dem Benutzer angezeigt werden kann.

Syntax

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

Parameter

dwDeviceID

Id des Telefongeräts, dessen Symbol angefordert wird.

lpszDeviceClass

Zeiger auf eine NULL-endende Zeichenfolge, die einen Geräteklassennamen identifiziert. Mit dieser Geräteklasse kann die Anwendung ein bestimmtes Untersymbol auswählen, das für diese Geräteklasse gilt. Dieser Parameter ist optional und kann NULL oder leer bleiben. In diesem Fall wird das Symbol der höchsten Ebene ausgewählt, das dem Telefongerät und nicht einem angegebenen Medienstreamgerät zugeordnet ist.

lphIcon

Zeiger auf einen Speicherort, an dem das Handle zum Symbol zurückgegeben wird.

Rückgabewert

Gibt null zurück, wenn die Anforderung erfolgreich ist, oder eine negative Fehlernummer, wenn ein Fehler auftritt. Mögliche Rückgabewerte sind:

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

Hinweise

Die phoneGetIcon-Funktion bewirkt, dass der Anbieter ein Handle (in lphIcon) an eine Symbolressource (abgerufen von LoadIcon) zurückgibt, die dem angegebenen Telefon zugeordnet ist. Das Symbolhandle gilt für eine Ressource, die dem Anbieter zugeordnet ist. Die Anwendung muss CopyIcon verwenden, wenn sie nach dem Entladen des Anbieters auf das Symbol verweisen möchte. Dies ist unwahrscheinlich, solange die Anwendung das Telefon geöffnet hat.

Der Parameter lpszDeviceClass ermöglicht es dem Anbieter, unterschiedliche Symbole basierend auf dem Typ des Diensts zurückzugeben, auf den der Aufrufer verweist. Die zulässigen Zeichenfolgen sind identisch mit denen für phoneGetID. Wenn das Telefon beispielsweise die Comm-API unterstützt, bewirkt die Übergabe von "COMM" als lpszDeviceClass , dass der Anbieter ein Symbol zurückgibt, das sich speziell auf die Comm-Gerätefunktionen des Dienstanbieters bezieht. Die Parameter "tapi/phone", "" oder NULL können verwendet werden, um das Symbol für den Telefondienst anzufordern.

Wenn der Anbieter bei Anwendungen, die eine TAPI-Version vor 2.0 verwenden, kein Symbol zurückgibt (unabhängig davon, ob die angegebene Geräteklasse ungültig ist oder der Anbieter keine Symbole unterstützt), ersetzt TAPI ein generisches Telefontelefongerätesymbol. Für Anwendungen, die TAPI Version 2.0 oder höher verwenden, ersetzt TAPI das Standardtelefonsymbol nur, wenn der LpszDeviceClass-Parameter "tapi/phone", "" oder NULL ist. Wenn die angegebene Geräteklasse ungültig ist oder der Anbieter keine Symbole für die Klasse unterstützt, gibt phoneGetIcon für jede andere Geräteklasse PHONEERR_INVALDEVICECLASS zurück.