Share via


NOTIFYICONDATAW 구조체(shellapi.h)

시스템에서 알림 영역에 알림을 표시해야 하는 정보를 포함합니다. Shell_NotifyIcon 사용합니다.

구문

typedef struct _NOTIFYICONDATAW {
  DWORD cbSize;
  HWND  hWnd;
  UINT  uID;
  UINT  uFlags;
  UINT  uCallbackMessage;
  HICON hIcon;
#if ...
  WCHAR szTip[64];
#else
  WCHAR szTip[128];
#endif
  DWORD dwState;
  DWORD dwStateMask;
  WCHAR szInfo[256];
  union {
    UINT uTimeout;
    UINT uVersion;
  } DUMMYUNIONNAME;
  WCHAR szInfoTitle[64];
  DWORD dwInfoFlags;
  GUID  guidItem;
  HICON hBalloonIcon;
} NOTIFYICONDATAW, *PNOTIFYICONDATAW;

멤버

cbSize

형식:DWORD

이 구조체의 크기(바이트)입니다.

hWnd

형식: HWND

알림 영역의 아이콘과 연결된 알림을 받는 창에 대한 핸들입니다.

uID

형식: UINT

작업 표시줄 아이콘의 애플리케이션 정의 식별자입니다. 셸은 (hWnd + 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. dwStatedwStateMask 멤버가 유효합니다.

NIF_INFO(0x00000010)

0x00000010. 풍선 알림을 표시합니다. szInfo, szInfoTitle, dwInfoFlagsuTimeout 멤버는 유효합니다. 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 매개 변수는 이벤트와 연결된 마우스 또는 키보드 메시지를 보유합니다. 예를 들어 포인터가 작업 표시줄 아이콘 위로 이동하면 lParamWM_MOUSEMOVE 설정됩니다.

uVersion 멤버가 NOTIFYICON_VERSION_4 경우 애플리케이션은 uCallbackMessage 멤버를 통해 애플리케이션 정의 메시지의 형태로 알림 이벤트를 계속 수신하지만 해당 메시지의 lParamwParam 매개 변수 해석은 다음과 같이 변경됩니다.

  • 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 이상.

참고 이 멤버는 Windows Vista를 기준으로 더 이상 사용되지 않습니다. 이제 알림 표시 시간은 시스템 내게 필요한 옵션 설정에 기반합니다.
 
uVersion과 공용 구조체. 알림에 대한 시간 제한 값(밀리초)입니다. 시스템은 최소 및 최대 시간 제한 값을 적용합니다. 너무 큰 uTimeout에 지정된 값은 최대값으로 설정됩니다. 기본값이 최소값으로 너무 작은 값입니다. 시스템 최소 및 최대 제한 시간 값은 현재 각각 10초 및 30초로 설정됩니다. uTimeout에 대한 자세한 내용은 설명을 참조하세요.

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 이상. 현재 사용자가 "조용한 시간"에 있는 경우 풍선 알림을 표시하지 마세요. 이는 새 사용자가 처음으로 자신의 계정에 로그인한 후 처음 1시간입니다. 이 시간 동안 대부분의 알림을 보내거나 표시해서는 안 됩니다. 이렇게 하면 사용자가 이러한 방해 요소 없이 새 컴퓨터 시스템에 익숙해질 수 있습니다. 운영 체제 업그레이드 또는 새로 설치한 후 각 사용자에 대해 조용한 시간도 발생합니다. 조용한 시간 동안 이 플래그와 함께 전송된 알림은 큐에 대기되지 않습니다. 그것은 단순히 파종 해제됩니다. 애플리케이션은 해당 시간에 여전히 유효한 경우 나중에 알림을 다시 전송할 수 있습니다.

애플리케이션은 조용한 시간이 발생할 수 있는 시기를 예측할 수 없으므로 이 플래그는 항상 조용한 시간을 존중하는 모든 애플리케이션의 적절한 알림에 설정하는 것이 좋습니다.

사용자가 USB 장치를 연결하거나 문서를 인쇄하는 경우와 같이 사용자가 사용자 작업에 대한 응답으로 피드백으로 예상하므로 조용한 시간에 특정 알림을 계속 보내야 합니다.

현재 사용자가 조용한 시간에 있지 않으면 이 플래그는 적용되지 않습니다.

NIIF_ICON_MASK(0x0000000F)

0x0000000F. Windows XP 이상. 예약되어 있습니다.

guidItem

형식: GUID

Windows XP 이상.

  • Windows 7 이상: 아이콘을 식별하는 등록된 GUID입니다. 이 값은 uID 를 재정의하며 아이콘을 식별하는 데 권장되는 방법입니다. uFlags 멤버에서 NIF_GUID 플래그를 설정해야 합니다.
  • Windows XP 및 Windows Vista: 예약됨; 은 0으로 설정해야 합니다.
애플리케이션이 Windows Vista와 Windows 7 모두에서 실행되도록 하려면 Windows 버전을 확인하고 Windows 7 이상인 경우 0이 아닌 guidItem 만 지정해야 합니다.

Shell_NotifyIcon 한 번의 호출에서 GUID로 알림 아이콘을 식별하는 경우 동일한 GUID를 사용하여 해당 아이콘을 처리하는 후속 Shell_NotifyIcon 호출에서 아이콘을 식별해야 합니다.

이 멤버에서 사용할 GUID를 생성하려면 Guidgen.exe 같은 GUID 생성 도구를 사용합니다.

hBalloonIcon

형식: HICON

Windows Vista 이상. 알림 영역 아이콘과 독립적으로 사용해야 하는 애플리케이션에서 제공하는 사용자 지정 알림 아이콘의 핸들입니다. 이 멤버가 NULL이 아니고 NIIF_USER 플래그가 dwInfoFlags 멤버에 설정된 경우 이 아이콘이 알림 아이콘으로 사용됩니다. 이 멤버가 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으로 설정해야 합니다.

참고 이 코드는 Windows 7 버전 번호와 관련이 있습니다. 이후 버전의 Windows 및 Windows Server는 guidItem 멤버를 지원할 것으로 예상되며, 이때 이 코드는 최신 버전 번호도 유효한 것으로 식별하도록 업데이트해야 합니다.
 
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 대한 일부 호출이 실패하는 경우 다음 사례 중 하나가 원인일 수 있습니다.
  1. NIF_GUID 플래그는 Shell_NotifyIcon 대한 모든 호출에서 설정되지 않았습니다. Shell_NotifyIcon 한 번의 호출에서 GUID로 알림 아이콘을 식별한 후에는 동일한 GUID를 사용하여 해당 아이콘을 처리하는 후속 Shell_NotifyIcon 호출에서 아이콘을 식별해야 합니다.
  2. 아이콘이 포함된 이진 파일이 이동되었습니다. 이진 파일의 경로는 아이콘의 GUID 등록에 포함되며 변경할 수 없습니다. 아이콘과 연결된 설정은 파일 경로 및 GUID가 변경되지 않은 경우에만 업그레이드를 통해 유지됩니다. 경로를 변경해야 하는 경우 애플리케이션은 기존 아이콘이 등록되었을 때 추가된 GUID 정보를 제거해야 합니다. 해당 정보가 제거되면 이진 파일을 새 위치로 이동하고 새 GUID로 다시 등록할 수 있습니다. 원래 GUID 등록과 연결된 모든 설정이 손실됩니다.

    이는 병렬 설치의 경우에도 발생합니다. 병렬 설치를 처리할 때 새 버전의 애플리케이션은 이진 파일의 GUID를 업데이트해야 합니다.

    참고 이동된 파일에 대한 유일한 예외는 원래 파일과 이동된 이진 파일이 모두 동일한 회사에서 Authenticode로 서명된 경우에 발생합니다. 이 경우 설정은 이동을 통해 유지됩니다.
     

참고

shellapi.h 헤더는 NOTIFYICONDATA를 별칭으로 정의하여 UNICODE 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

   
지원되는 최소 클라이언트 Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버 Windows 2000 Server[데스크톱 앱만]
머리글 shellapi.h

추가 정보

알림 및 알림 영역