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

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

사용자가 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으로 설정해야 합니다.
애플리케이션이 Windows Vista와 Windows 7 모두에서 실행되도록 하려면 Windows 버전을 검사 Windows 7 이상에서는 0이 아닌 guidItem만 지정해야 합니다.

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으로 설정해야 합니다.

참고 이 코드는 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

추가 정보

알림 및 알림 영역