NOTIFYICONDATAA 구조체(shellapi.h)
시스템에서 알림 영역에 알림을 표시해야 하는 정보를 포함합니다. Shell_NotifyIcon 사용합니다.
구문
typedef struct _NOTIFYICONDATAA {
DWORD cbSize;
HWND hWnd;
UINT uID;
UINT uFlags;
UINT uCallbackMessage;
HICON hIcon;
#if ...
CHAR szTip[64];
#else
CHAR szTip[128];
#endif
DWORD dwState;
DWORD dwStateMask;
CHAR szInfo[256];
union {
UINT uTimeout;
UINT uVersion;
} DUMMYUNIONNAME;
CHAR szInfoTitle[64];
DWORD dwInfoFlags;
GUID guidItem;
HICON hBalloonIcon;
} NOTIFYICONDATAA, *PNOTIFYICONDATAA;
멤버
cbSize
형식:DWORD
이 구조체의 크기(바이트)입니다.
hWnd
형식: HWND
알림 영역의 아이콘과 연결된 알림을 받는 창에 대한 핸들입니다.
uID
형식: UINT
작업 표시줄 아이콘의 애플리케이션 정의 식별자입니다. Shell은 (hWnd plus uID) 또는 guidItem 을 사용하여 Shell_NotifyIcon 호출될 때 작동할 아이콘을 식별합니다. 각각 다른 uID를 할당하여 단일 hWnd와 연결된 여러 아이콘을 가질 수 있습니다. guidItem을 지정하면 uID가 무시됩니다.
uFlags
형식: UINT
구조체의 다른 멤버 중 유효한 데이터를 포함하는 것을 나타내거나 도구 설명에 표시 방법에 대한 추가 정보를 제공하는 플래그입니다. 이 멤버는 다음 값의 조합일 수 있습니다.
NIF_MESSAGE(0x00000001)
0x00000001. uCallbackMessage 멤버가 유효합니다.
NIF_ICON(0x00000002)
0x00000002. hIcon 멤버가 유효합니다.
NIF_TIP(0x00000004)
0x00000004. szTip 멤버가 유효합니다.
NIF_STATE(0x00000008)
0x00000008. dwState 및 dwStateMask 멤버는 유효합니다.
NIF_INFO(0x00000010)
0x00000010. 풍선 알림을 표시합니다. szInfo, szInfoTitle, dwInfoFlags 및 uTimeout 멤버는 유효합니다. uTimeout은 Windows 2000 및 Windows XP에서만 유효합니다.
- 풍선 알림을 표시하려면 NIF_INFO 지정하고 szInfo에서 텍스트를 제공합니다.
- 풍선 알림을 제거하려면 NIF_INFO 지정하고 szInfo를 통해 빈 문자열을 제공합니다.
- 알림을 표시하지 않고 알림 영역 아이콘을 추가하려면 NIF_INFO 플래그를 설정하지 마세요.
NIF_GUID(0x00000020)
0x00000020.
- Windows 7 이상: guidItem 이 유효합니다.
- Windows Vista 및 이전 버전: 예약됨.
NIF_REALTIME(0x00000040)
0x00000040. Windows Vista 이상. 풍선 알림을 즉시 표시할 수 없는 경우 삭제합니다. 나중에 표시될 경우 의미가 없거나 오해의 소지가 있는 실시간 정보를 나타내는 알림에 이 플래그를 사용합니다. 예를 들어 "전화가 울리고 있습니다."라는 메시지가 표시됩니다. NIF_REALTIME NIF_INFO 플래그와 결합된 경우에만 의미가 있습니다.
NIF_SHOWTIP(0x00000080)
0x00000080. Windows Vista 이상. 표준 도구 설명을 사용합니다. 일반적으로 uVersion 이 NOTIFYICON_VERSION_4 설정되면 표준 도구 설명이 표시되지 않으며 애플리케이션에서 그린 팝업 UI로 대체될 수 있습니다. 애플리케이션이 NOTIFYICON_VERSION_4 사용하여 표준 도구 설명을 표시하려는 경우 표준 도구 설명이 계속 표시되어야 함을 나타내는 NIF_SHOWTIP 지정할 수 있습니다.
uCallbackMessage
형식: UINT
애플리케이션에서 정의한 메시지 식별자입니다. 시스템은 이 식별자를 사용하여 hWnd로 식별된 창에 알림 메시지를 보냅니다. 이러한 알림 메시지는 아이콘의 경계 사각형에서 마우스 이벤트 또는 가리키기가 발생하거나, 아이콘을 키보드로 선택하거나 활성화할 때 또는 풍선 알림에서 이러한 작업이 발생할 때 전송됩니다.
uVersion 멤버가 0이거나 NOTIFYICON_VERSION 경우 메시지의 wParam 매개 변수에는 이벤트가 발생한 작업 표시줄 아이콘의 식별자가 포함됩니다. 이 식별자는 길이가 32비트일 수 있습니다. lParam 매개 변수는 이벤트와 연결된 마우스 또는 키보드 메시지를 보유합니다. 예를 들어 포인터가 작업 표시줄 아이콘 위로 이동하면 lParam 이 WM_MOUSEMOVE 설정됩니다.
uVersion 멤버가 NOTIFYICON_VERSION_4 경우 애플리케이션은 uCallbackMessage 멤버를 통해 애플리케이션 정의 메시지 형식으로 알림 이벤트를 계속 수신하지만 해당 메시지의 lParam 및 wParam 매개 변수 해석은 다음과 같이 변경됩니다.
- LOWORD(lParam) 에는 NIN_BALLOONSHOW, NIN_POPUPOPEN 또는 WM_CONTEXTMENU 같은 알림 이벤트가 포함되어 있습니다.
- HIWORD(lParam) 에는 아이콘 ID가 포함되어 있습니다. 아이콘 ID는 16비트 길이로 제한됩니다.
- GET_X_LPARAM(wParam) 은 알림 이벤트 NIN_POPUPOPEN, NIN_SELECT, NIN_KEYSELECT 및 WM_MOUSEFIRST 및 WM_MOUSELAST 사이의 모든 마우스 메시지에 대한 X 앵커 좌표를 반환합니다. 이러한 메시지가 키보드에서 생성되는 경우 wParam 은 대상 아이콘의 왼쪽 위 모서리로 설정됩니다. 다른 모든 메시지의 경우 wParam 은 정의되지 않습니다.
- GET_Y_LPARAM(wParam) 은 X 앵커에 정의된 대로 알림 이벤트 및 메시지에 대한 Y 앵커 좌표를 반환합니다.
hIcon
형식: HICON
추가, 수정 또는 삭제할 아이콘에 대한 핸들입니다. Windows XP 이상에서는 최대 32개의 BPP 아이콘을 지원합니다.
16x16 픽셀 아이콘만 제공되면 시스템에서 높은 dpi 값으로 설정된 더 큰 크기로 크기가 조정됩니다. 이로 인해 매력적이지 않은 결과가 발생할 수 있습니다. 리소스 파일에 16x16 픽셀 아이콘과 32x32 아이콘을 모두 제공하는 것이 좋습니다. LoadIconMetric을 사용하여 올바른 아이콘이 로드되고 적절하게 크기 조정되었는지 확인합니다. 코드 예제는 비고를 참조하세요.
szTip[64]
형식: TCHAR[64]
표준 도구 설명의 텍스트를 지정하는 null로 끝나는 문자열입니다. 종료 null 문자를 포함하여 최대 64자를 가질 수 있습니다.
Windows 2000 이상의 경우 szTip 은 종료 null 문자를 포함하여 최대 128자를 가질 수 있습니다.
szTip[128]
형식: TCHAR[64]
표준 도구 설명의 텍스트를 지정하는 null로 끝나는 문자열입니다. 종료 null 문자를 포함하여 최대 64자를 가질 수 있습니다.
Windows 2000 이상의 경우 szTip 은 종료 null 문자를 포함하여 최대 128자를 가질 수 있습니다.
dwState
형식:DWORD
Windows 2000 이상. 아이콘의 상태입니다. 다음 값 중 하나 또는 둘 다:
NIS_HIDDEN(0x00000001)
0x00000001. 아이콘이 숨겨져 있습니다.
NIS_SHAREDICON(0x00000002)
0x00000002. 아이콘 리소스는 여러 아이콘 간에 공유됩니다.
dwStateMask
형식:DWORD
Windows 2000 이상. dwState 멤버의 어떤 비트를 검색하거나 수정할지 지정하는 값입니다. 가능한 값은 dwState의 값과 동일합니다. 예를 들어 이 멤버를 NIS_HIDDEN 설정하면 값에 관계없이 아이콘 공유 비트가 무시되는 동안 항목의 숨겨진 상태만 수정됩니다.
szInfo[256]
형식: TCHAR[256]
Windows 2000 이상. 풍선 알림에 표시할 텍스트를 지정하는 null로 끝나는 문자열입니다. 종료되는 null 문자를 포함하여 최대 256자를 포함할 수 있지만 지역화를 수용하려면 영어로 200자로 제한해야 합니다. UI에서 풍선 알림을 제거하려면 아이콘(NIM_DELETE 포함)을 삭제하거나 uFlags에서 NIF_INFO 플래그를 설정하고 szInfo를 빈 문자열로 설정합니다.
DUMMYUNIONNAME
DUMMYUNIONNAME.uTimeout
형식: UINT
Windows 2000 이상.
DUMMYUNIONNAME.uVersion
형식: UINT
Windows 2000 이상. uTimeout과 공용 구조체(Windows Vista를 기준으로 사용되지 않음) 사용해야 하는 셸 알림 아이콘 인터페이스의 버전을 지정합니다. 이러한 버전의 차이점에 대한 자세한 내용은 Shell_NotifyIcon 참조하세요. 이 멤버는 Shell_NotifyIcon 사용하여 NIM_SETVERSION메시지를 보낼 때만 사용됩니다.
szInfoTitle[64]
형식: TCHAR[64]
Windows 2000 이상. 풍선 알림의 제목을 지정하는 null로 끝나는 문자열입니다. 이 제목은 텍스트 바로 위에 더 큰 글꼴로 나타납니다. 종료 null 문자를 포함하여 최대 64자를 포함할 수 있지만 지역화를 수용하려면 영어로 48자로 제한해야 합니다.
dwInfoFlags
형식:DWORD
Windows 2000 이상. 풍선 알림의 동작 및 모양을 수정하도록 설정할 수 있는 플래그입니다. 아이콘은 제목 왼쪽에 배치됩니다. szInfoTitle 멤버의 길이가 0이면 아이콘이 표시되지 않습니다.
NIIF_NONE(0x00000000)
0x00000000. 아이콘이 없습니다.
NIIF_INFO(0x00000001)
0x00000001. 정보 아이콘
NIIF_WARNING(0x00000002)
0x00000002. 경고 아이콘
NIIF_ERROR(0x00000003)
0x00000003. 오류 아이콘입니다.
NIIF_USER(0x00000004)
0x00000004. Windows XP SP2 이상.
- Windows XP: hIcon 에서 식별된 아이콘을 알림 풍선의 제목 아이콘으로 사용합니다.
- Windows Vista 이상: hBalloonIcon 에서 식별된 아이콘을 알림 풍선의 제목 아이콘으로 사용합니다.
NIIF_NOSOUND(0x00000010)
0x00000010. Windows XP 이상. 연결된 소리를 재생하지 마세요. 알림에만 적용됩니다.
NIIF_LARGE_ICON(0x00000020)
0x00000020. Windows Vista 이상. 아이콘의 큰 버전은 알림 아이콘으로 사용해야 합니다. x SM_CYICON SM_CXICON 차원이 있는 아이콘에 해당합니다. 이 플래그를 설정하지 않으면 x SM_CYSMICON SM_CXSMICON 차원이 있는 아이콘이 사용됩니다.
- 이 플래그는 모든 스톡 아이콘과 함께 사용할 수 있습니다.
- 이전 사용자 지정 아이콘( hIcon과 NIIF_USER)을 사용하는 애플리케이션은 트레이 아이콘(hIcon)에 새 SM_CXICON x SM_CYICON 버전을 제공해야 합니다. 이러한 아이콘은 시스템 트레이 또는 SCA(시스템 제어 영역)에 표시될 때 축소됩니다.
- 새로운 사용자 지정 아이콘( hBalloonIcon을 사용하는 NIIF_USER)은 제공된 아이콘(hBalloonIcon)에서 SM_CXICON x SM_CYICON 버전을 제공해야 합니다.
NIIF_RESPECT_QUIET_TIME(0x00000080)
0x00000080. Windows 7 이상. 현재 사용자가 "조용한 시간"에 있는 경우 풍선 알림을 표시하지 마세요. 이는 새 사용자가 처음으로 자신의 계정에 로그인한 후 첫 번째 시간입니다. 이 시간 동안 대부분의 알림을 보내거나 표시해서는 안 됩니다. 이렇게 하면 사용자가 이러한 방해 요소 없이 새 컴퓨터 시스템에 익숙해질 수 있습니다. 운영 체제 업그레이드 또는 클린 설치 후 각 사용자에 대해 조용한 시간도 발생합니다. 조용한 시간 동안 이 플래그와 함께 전송된 알림은 큐에 대기되지 않습니다. 그것은 단순히 파종 해제됩니다. 애플리케이션은 해당 시간에 여전히 유효한 경우 나중에 알림을 다시 전송할 수 있습니다.
애플리케이션은 조용한 시간이 발생할 수 있는 시기를 예측할 수 없으므로 이 플래그는 항상 조용한 시간을 존중하는 모든 애플리케이션의 적절한 알림에 설정하는 것이 좋습니다.
사용자가 USB 디바이스에 연결하거나 문서를 인쇄할 때 instance 경우 사용자가 사용자 작업에 대한 응답으로 피드백으로 예상되므로 조용한 시간 동안 특정 알림이 계속 전송되어야 합니다.
현재 사용자가 조용한 시간에 있지 않으면 이 플래그는 영향을 주지 않습니다.
NIIF_ICON_MASK(0x0000000F)
0x0000000F. Windows XP 이상. 예약되어 있습니다.
guidItem
형식: GUID
Windows XP 이상.
- Windows 7 이상: 아이콘을 식별하는 등록된 GUID입니다. 이 값은 uID 를 재정의하고 아이콘을 식별하는 권장 방법입니다. uFlags 멤버에서 NIF_GUID 플래그를 설정해야 합니다.
- Windows XP 및 Windows Vista: 예약됨; 은 0으로 설정해야 합니다.
Shell_NotifyIcon 한 번의 호출에서 GUID로 알림 아이콘을 식별하는 경우 동일한 GUID를 사용하여 해당 아이콘을 처리하는 후속 Shell_NotifyIcon 호출에서 아이콘을 식별해야 합니다.
이 멤버에서 사용할 GUID를 생성하려면 Guidgen.exe 같은 GUID 생성 도구를 사용합니다.
hBalloonIcon
형식: HICON
Windows Vista 이상. 알림 영역 아이콘과 독립적으로 사용해야 하는 애플리케이션에서 제공하는 사용자 지정된 알림 아이콘의 핸들입니다. 이 멤버가 NULL이 아니고 dwInfoFlags 멤버에 NIIF_USER 플래그가 설정된 경우 이 아이콘이 알림 아이콘으로 사용됩니다. 이 멤버가 NULL이면 레거시 동작이 수행됩니다.
설명
알림 UI 및 콘텐츠 모범 사례에 대한 자세한 내용은 Windows 사용자 환경 상호 작용 지침의 "알림"을 참조하세요.
uFlags 멤버에서 NIF_INFO 플래그를 설정하면 풍선 스타일 알림이 사용됩니다. 이러한 알림에 대한 자세한 내용은 풍선 도구 설명을 참조하세요.
작업 표시줄에 대해 한 번에 둘 이상의 풍선 알림을 표시할 수 없습니다. 애플리케이션이 이미 표시되어 있을 때 알림을 표시하려고 하면 이전 알림이 사라지면 새 알림이 큐에 대기되고 표시됩니다. Windows Vista 이전의 Windows 버전에서는 원래 알림의 uTimeout 값에 관계없이 시스템 최소 시간 제한 길이 이상에 대해 기존 알림이 표시될 때까지 새 알림이 표시되지 않습니다. 사용자가 컴퓨터를 사용하지 않는 것처럼 보이면 이번에는 시스템이 시간 제한으로 계산되지 않습니다.
이 구조체의 여러 멤버는 Windows 2000 이상에서만 지원됩니다. 이러한 멤버를 사용하도록 설정하려면 헤더에 다음 줄 중 하나를 포함합니다.
// Windows Vista and later:
#define NTDDI_VERSION NTDDI_WIN2K
#define NTDDI_VERSION NTDDI_WINXP
#define NTDDI_VERSION NTDDI_VISTA
// Windows XP and earlier:
#define _WIN32_IE 0x0500
크기를 사용하여 구조를 초기화해야 합니다. 현재 정의된 구조체의 크기를 사용하는 경우 더 작은 구조가 필요한 이전 버전의 Shell32.dll 애플리케이션이 실행되지 않을 수 있습니다. 적절한 버전 번호를 정의하여 이전 버전의 Shell32.dll 대해 애플리케이션을 실행할 수 있습니다( 셸 및 공용 컨트롤 버전 참조). 그러나 애플리케이션도 최신 시스템에서 실행해야 하는 경우 문제가 발생할 수 있습니다.
NOTIFYICONDATA 구조체의 크기를 적절하게 설정하여 현재 헤더 파일을 사용하는 동안 모든 Shell32.dll 버전과의 애플리케이션 호환성을 유지할 수 있습니다. 구조를 초기화하기 전에 DllGetVersion 을 사용하여 시스템에 설치된 Shell32.dll 버전을 확인하고 다음 값 중 하나를 사용하여 cbSize 를 초기화합니다.
Shell32.dll 버전 | cbSize |
---|---|
6.0.6 이상(Windows Vista 이상) | sizeof(NOTIFYICONDATA) |
6.0(Windows XP) | NOTIFYICONDATA_V3_SIZE |
5.0(Windows 2000) | NOTIFYICONDATA_V2_SIZE |
5.0보다 낮은 버전 | NOTIFYICONDATA_V1_SIZE |
cbSize에 이 값을 사용하면 애플리케이션이 이전 Shell32.dll 버전과 호환되는 메서드에서 NOTIFYICONDATA를 사용할 수 있습니다.
다음 코드 예제에서는 guidItem 멤버를 사용하는 애플리케이션이 Windows Vista와 Windows 7 모두에서 실행되도록 설정할 수 있는 버전 확인을 보여 줍니다. 운영 체제가 Windows 7인 경우 TRUE 를 반환하는 부울 함수를 제공합니다. 이 멤버가 TRUE를 반환하지 않는 한 guidItem 멤버를 0으로 설정해야 합니다.
BOOL IsWin7OrLater()
{
// Initialize the OSVERSIONINFOEX structure.
OSVERSIONINFOEX osvi;
ZeroMemory(&osvi, sizeof(OSVERSIONINFOEX));
osvi.dwOSVersionInfoSize = sizeof(OSVERSIONINFOEX);
osvi.dwMajorVersion = 6;
osvi.dwMinorVersion = 1;
// Initialize the condition mask.
DWORDLONG dwlConditionMask = 0;
VER_SET_CONDITION(dwlConditionMask, VER_MAJORVERSION, VER_GREATER_EQUAL);
VER_SET_CONDITION(dwlConditionMask, VER_MINORVERSION, VER_GREATER_EQUAL);
// Perform the test.
return VerifyVersionInfo(&osvi,
VER_MAJORVERSION | VER_MINORVERSION,
dwlConditionMask);
}
다음 코드 예제에서는 LoadIconMetric 을 사용하여 높은 DPI와 함께 사용할 아이콘을 로드하는 방법을 보여줍니다.
// Declare NOTIFYICONDATA details.
// Error handling is omitted here for brevity. Do not omit it in your code.
NOTIFYICONDATA nid = {};
nid.cbSize = sizeof(nid);
nid.hWnd = hWnd;
nid.uFlags = NIF_ICON | NIF_TIP | NIF_GUID;
// Note: This is an example GUID only and should not be used.
// Normally, you should use a GUID-generating tool to provide the value to
// assign to guidItem.
static const GUID myGUID =
{0x23977b55, 0x10e0, 0x4041, {0xb8, 0x62, 0xb1, 0x95, 0x41, 0x96, 0x36, 0x69}};
nid.guidItem = myGUID;
// This text will be shown as the icon's tooltip.
StringCchCopy(nid.szTip, ARRAYSIZE(nid.szTip), L"Test application");
// Load the icon for high DPI.
LoadIconMetric(hInst, MAKEINTRESOURCE(IDI_SMALL), LIM_SMALL, &(nid.hIcon));
// Show the notification.
Shell_NotifyIcon(NIM_ADD, &nid) ? S_OK : E_FAIL;
문제 해결
guidItem 멤버를 사용하여 아이콘을 식별할 때 해당 아이콘이 표시되지 않거나 Shell_NotifyIcon 대한 일부 호출이 실패하는 경우 다음 사례 중 하나가 원인일 수 있습니다.- NIF_GUID 플래그는 Shell_NotifyIcon 대한 모든 호출에서 설정되지 않았습니다. Shell_NotifyIcon 한 번의 호출에서 GUID가 있는 알림 아이콘을 식별한 후에는 동일한 GUID를 사용하여 해당 아이콘을 처리하는 후속 Shell_NotifyIcon 호출에서 아이콘을 식별해야 합니다.
-
아이콘이 포함된 이진 파일이 이동되었습니다. 이진 파일의 경로는 아이콘의 GUID 등록에 포함되며 변경할 수 없습니다. 아이콘과 연결된 설정은 파일 경로 및 GUID가 변경되지 않은 경우에만 업그레이드를 통해 유지됩니다. 경로를 변경해야 하는 경우 애플리케이션은 기존 아이콘이 등록되었을 때 추가된 GUID 정보를 제거해야 합니다. 해당 정보가 제거되면 이진 파일을 새 위치로 이동하고 새 GUID로 다시 등록할 수 있습니다. 원래 GUID 등록과 연결된 모든 설정이 손실됩니다.
이는 병렬 설치의 경우에도 발생합니다. 병렬 설치를 처리할 때 새 버전의 애플리케이션은 이진 파일의 GUID를 업데이트해야 합니다.
참고 이동된 파일에 대한 유일한 예외는 원래 파일과 이동된 이진 파일이 모두 동일한 회사에서 Authenticode로 서명된 경우에 발생합니다. 이 경우 설정은 이동을 통해 유지됩니다.
참고
shellapi.h 헤더는 NOTIFYICONDATA를 별칭으로 정의하여 UNICODE 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.
요구 사항
요구 사항 | 값 |
---|---|
지원되는 최소 클라이언트 | Windows XP [데스크톱 앱만 해당] |
지원되는 최소 서버 | Windows 2000 Server[데스크톱 앱만] |
머리글 | shellapi.h |