CreateNamedPipeA 함수(winbase.h)
명명된 파이프의 instance 만들고 후속 파이프 작업에 대한 핸들을 반환합니다. 명명된 파이프 서버 프로세스는 이 함수를 사용하여 명명된 특정 파이프의 첫 번째 instance 만들고 기본 특성을 설정하거나 기존 명명된 파이프의 새 instance 만듭니다.
구문
HANDLE CreateNamedPipeA(
[in] LPCSTR lpName,
[in] DWORD dwOpenMode,
[in] DWORD dwPipeMode,
[in] DWORD nMaxInstances,
[in] DWORD nOutBufferSize,
[in] DWORD nInBufferSize,
[in] DWORD nDefaultTimeOut,
[in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes
);
매개 변수
[in] lpName
고유한 파이프 이름입니다. 이 문자열은 다음 형식이어야 합니다.
\\.\pipe\pipename
이름의 파이프 이름 부분에는 숫자 및 특수 문자를 포함하여 백슬래시 이외의 문자가 포함될 수 있습니다. 전체 파이프 이름 문자열은 최대 256자까지 가능합니다. 파이프 이름은 대/소문자를 구분하지 않습니다.
[in] dwOpenMode
열린 모드입니다.
dwOpenMode가 다음 표에 나열된 플래그 또는 0 이외의 항목을 지정하면 함수가 실패합니다.
이 매개 변수는 다음 파이프 액세스 모드 중 하나를 지정해야 합니다. 파이프의 각 instance 대해 동일한 모드를 지정해야 합니다.
| 모드 | 의미 |
|---|---|
|
파이프는 양방향입니다. 서버 및 클라이언트 프로세스는 파이프에서 읽고 파이프에 쓸 수 있습니다. 이 모드는 서버에 파이프에 대한 GENERIC_READ 및 GENERIC_WRITE 액세스와 동등한 권한을 부여합니다. 클라이언트는 CreateFile 함수를 사용하여 파이프에 연결할 때 GENERIC_READ 또는 GENERIC_WRITE 또는 둘 다를 지정할 수 있습니다. |
|
파이프의 데이터 흐름은 클라이언트에서 서버로만 이동합니다. 이 모드는 서버에 파이프에 대한 GENERIC_READ 액세스와 동등한 권한을 부여합니다. 클라이언트는 파이프에 연결할 때 GENERIC_WRITE 액세스를 지정해야 합니다. 클라이언트가 GetNamedPipeInfo 또는 GetNamedPipeHandleState 함수를 호출하여 파이프 설정을 읽어야 하는 경우 클라이언트는 파이프에 연결할 때 GENERIC_WRITE 및 FILE_READ_ATTRIBUTES 액세스를 지정해야 합니다. |
|
파이프의 데이터 흐름은 서버에서 클라이언트로만 이동합니다. 이 모드는 서버에 파이프에 대한 GENERIC_WRITE 액세스와 동등한 권한을 부여합니다. 클라이언트는 파이프에 연결할 때 GENERIC_READ 액세스를 지정해야 합니다. 클라이언트가 SetNamedPipeHandleState 함수를 호출하여 파이프 설정을 변경해야 하는 경우 클라이언트는 파이프에 연결할 때 GENERIC_READ 지정하고 액세스를 FILE_WRITE_ATTRIBUTES 합니다. |
이 매개 변수에는 쓰기 및 겹치는 모드를 사용하도록 설정하는 다음 플래그 중 하나 이상이 포함될 수도 있습니다. 이러한 모드는 동일한 파이프의 다른 인스턴스에 대해 다를 수 있습니다.
| 모드 | 의미 |
|---|---|
|
이 플래그를 사용하여 파이프의 여러 인스턴스를 만들려고 하면 첫 번째 instance 만드는 데 성공하지만 ERROR_ACCESS_DENIED 다음 instance 만들지 못합니다. |
|
쓰기 모드를 사용할 수 있습니다. 이 모드는 바이트 형식 파이프에 대한 쓰기 작업에만 영향을 줍니다. 그런 다음 클라이언트 및 서버 프로세스가 서로 다른 컴퓨터에 있는 경우에만 적용됩니다. 이 모드를 사용하도록 설정하면 기록된 데이터가 네트워크를 통해 전송되고 원격 컴퓨터의 파이프 버퍼에 있게 될 때까지 명명된 파이프에 쓰는 함수가 반환되지 않습니다. 이 모드를 사용하도록 설정하지 않으면 최소 바이트 수가 누적되거나 최대 시간이 경과할 때까지 데이터를 버퍼링하여 네트워크 작업의 효율성을 향상시킵니다. |
|
겹치는 모드를 사용할 수 있습니다. 이 모드를 사용하도록 설정하면 완료하는 데 상당한 시간이 걸릴 수 있는 읽기, 쓰기 및 연결 작업을 수행하는 함수가 즉시 반환될 수 있습니다. 이 모드를 사용하면 작업을 시작한 스레드가 백그라운드에서 시간이 많이 걸리는 작업을 실행하는 동안 다른 작업을 수행할 수 있습니다. 예를 들어 겹치는 모드에서 스레드는 파이프의 여러 인스턴스에서 동시 입력 및 출력(I/O) 작업을 처리하거나 동일한 파이프 핸들에서 동시 읽기 및 쓰기 작업을 수행할 수 있습니다. 겹치는 모드를 사용하도록 설정하지 않으면 파이프 핸들에서 읽기, 쓰기 및 연결 작업을 수행하는 함수는 작업이 완료될 때까지 반환되지 않습니다. ReadFileEx 및 WriteFileEx 함수는 겹치는 모드의 파이프 핸들에서만 사용할 수 있습니다. ReadFile, WriteFile, ConnectNamedPipe 및 TransactNamedPipe 함수는 동기적으로 또는 겹치는 작업으로 실행할 수 있습니다. |
이 매개 변수에는 다음 보안 액세스 모드의 조합이 포함될 수 있습니다. 이러한 모드는 동일한 파이프의 다른 인스턴스에 대해 다를 수 있습니다.
| 모드 | 의미 |
|---|---|
|
호출자는 명명된 파이프의 임의 ACL(액세스 제어 목록)에 대한 쓰기 권한을 갖습니다. |
|
호출자는 명명된 파이프의 소유자에 대한 쓰기 권한을 갖습니다. |
|
호출자는 명명된 파이프의 SACL에 대한 쓰기 권한을 갖습니다. 자세한 내용은 ACL(Access-Control Lists) 및 SACL 액세스 권한을 참조하세요. |
[in] dwPipeMode
파이프 모드입니다.
dwPipeMode가 다음 표에 나열된 플래그 또는 0 이외의 항목을 지정하면 함수가 실패합니다.
다음 형식 모드 중 하나를 지정할 수 있습니다. 파이프의 각 instance 대해 동일한 형식 모드를 지정해야 합니다.
| 모드 | 의미 |
|---|---|
|
데이터는 파이프에 바이트 스트림으로 기록됩니다. 이 모드는 PIPE_READMODE_MESSAGE 사용할 수 없습니다. 파이프는 다른 쓰기 작업 중에 작성된 바이트를 구분하지 않습니다. |
|
데이터는 메시지 스트림으로 파이프에 기록됩니다. 파이프는 각 쓰기 작업 중에 작성된 바이트를 메시지 단위로 처리합니다. GetLastError 함수는 메시지를 완전히 읽지 않으면 ERROR_MORE_DATA 반환합니다. 이 모드는 PIPE_READMODE_MESSAGE 또는 PIPE_READMODE_BYTE 사용할 수 있습니다. |
다음 읽기 모드 중 하나를 지정할 수 있습니다. 동일한 파이프의 다른 인스턴스는 다른 읽기 모드를 지정할 수 있습니다.
다음 대기 모드 중 하나를 지정할 수 있습니다. 동일한 파이프의 다른 인스턴스는 서로 다른 대기 모드를 지정할 수 있습니다.
| 모드 | 의미 |
|---|---|
|
차단 모드를 사용할 수 있습니다. 파이프 핸들이 ReadFile, WriteFile 또는 ConnectNamedPipe 함수에 지정되면 읽을 데이터가 있거나 모든 데이터가 기록되거나 클라이언트가 연결될 때까지 작업이 완료되지 않습니다. 이 모드를 사용하면 클라이언트 프로세스가 작업을 수행하기 위해 어떤 상황에서는 무기한 대기할 수 있습니다. |
|
차단 해제 모드가 사용하도록 설정됩니다. 이 모드에서는 ReadFile, WriteFile 및 ConnectNamedPipe가 항상 즉시 반환됩니다.
비 차단 모드는 Microsoft LAN Manager 버전 2.0과의 호환성을 위해 지원되며 명명된 파이프를 사용하여 비동기 I/O를 달성하는 데 사용하면 안 됩니다. 비동기 파이프 I/O에 대한 자세한 내용은 동기 및 겹치는 입력 및 출력을 참조하세요. |
다음 원격 클라이언트 모드 중 하나를 지정할 수 있습니다. 동일한 파이프의 다른 인스턴스는 서로 다른 원격 클라이언트 모드를 지정할 수 있습니다.
| 모드 | 의미 |
|---|---|
|
원격 클라이언트의 Connections 파이프의 보안 설명자에 대해 수락하고 확인할 수 있습니다. |
|
원격 클라이언트의 Connections 자동으로 거부됩니다. |
[in] nMaxInstances
이 파이프에 대해 만들 수 있는 최대 인스턴스 수입니다. 파이프의 첫 번째 instance 이 값을 지정할 수 있습니다. 파이프의 다른 인스턴스에 대해 동일한 숫자를 지정해야 합니다. 허용되는 값은 1~ PIPE_UNLIMITED_INSTANCES (255) 범위에 있습니다.
이 매개 변수가 PIPE_UNLIMITED_INSTANCES 경우 만들 수 있는 파이프 인스턴스 수는 시스템 리소스의 가용성에 의해서만 제한됩니다. nMaxInstances가 PIPE_UNLIMITED_INSTANCES보다 크면 반환 값이 INVALID_HANDLE_VALUEGetLastError는 ERROR_INVALID_PARAMETER 반환합니다.
[in] nOutBufferSize
출력 버퍼에 대해 예약할 바이트 수입니다. 명명된 파이프 버퍼 크기 조정에 대한 자세한 내용은 다음 설명 섹션을 참조하세요.
[in] nInBufferSize
입력 버퍼에 대해 예약할 바이트 수입니다. 명명된 파이프 버퍼 크기 조정에 대한 자세한 내용은 다음 설명 섹션을 참조하세요.
[in] nDefaultTimeOut
WaitNamedPipe 함수가 NMPWAIT_USE_DEFAULT_WAIT 지정하는 경우 기본 제한 시간 값(밀리초)입니다. 명명된 파이프의 각 instance 동일한 값을 지정해야 합니다.
값이 0이면 기본 제한 시간이 50밀리초입니다.
[in, optional] lpSecurityAttributes
명명된 새 파이프에 대한 보안 설명자를 지정하고 자식 프로세스가 반환된 핸들을 상속할 수 있는지 여부를 결정하는 SECURITY_ATTRIBUTES 구조체에 대한 포인터입니다. lpSecurityAttributes가 NULL인 경우 명명된 파이프는 기본 보안 설명자를 가져오고 핸들을 상속할 수 없습니다. 명명된 파이프에 대한 기본 보안 설명자의 ACL은 LocalSystem 계정, 관리자 및 작성자 소유자에게 모든 권한을 부여합니다. 또한 모든 사용자 그룹 및 익명 계정의 구성원에게 읽기 권한을 부여합니다.
반환 값
함수가 성공하면 반환 값은 명명된 파이프 instance 서버 끝에 대한 핸들입니다.
함수가 실패하는 경우 반환 값은 INVALID_HANDLE_VALUE입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.
설명
CreateNamedPipe를 사용하여 명명된 파이프의 instance 만들려면 명명된 파이프 개체에 대한 FILE_CREATE_PIPE_INSTANCE 액세스 권한이 있어야 합니다. 명명된 새 파이프를 만드는 경우 보안 특성 매개 변수의 ACL(액세스 제어 목록)은 명명된 파이프에 대한 임의 액세스 제어를 정의합니다.
명명된 파이프의 모든 인스턴스는 동일한 파이프 유형(바이트 형식 또는 메시지 형식), 파이프 액세스(이중, 인바운드 또는 아웃바운드), instance 개수 및 제한 시간 값을 지정해야 합니다. 다른 값을 사용하는 경우 이 함수는 실패하고 GetLastError 는 ERROR_ACCESS_DENIED 반환합니다.
클라이언트 프로세스는 CreateFile 또는 CallNamedPipe 함수를 사용하여 명명된 파이프에 연결합니다. 서버 쪽이 메시지 모드에 있더라도 명명된 파이프의 클라이언트 쪽이 바이트 모드에서 시작됩니다. 데이터 수신 문제를 방지하려면 클라이언트 쪽도 메시지 모드로 설정합니다. 파이프 모드를 변경하려면 파이프 클라이언트가 GENERIC_READFILE_WRITE_ATTRIBUTES 액세스 권한이 있는 읽기 전용 파이프를 열어야 합니다.
파이프 서버는 파이프 클라이언트가 시작될 때까지 차단 읽기 작업을 수행해서는 안 됩니다. 그렇지 않으면 경합 상태가 발생할 수 있습니다. 이는 일반적으로 C 런타임과 같은 초기화 코드가 상속된 핸들을 잠그고 검사해야 하는 경우에 발생합니다.
명명된 파이프를 만들 때마다 시스템은 커널에서 사용하는 실제 메모리인 비페이지 풀을 사용하여 인바운드 및/또는 아웃바운드 버퍼를 만듭니다. 만들 수 있는 파이프 인스턴스(스레드 및 프로세스와 같은 개체)의 수는 사용 가능한 비페이지 풀에 의해 제한됩니다. 각 읽기 또는 쓰기 요청에는 읽기 또는 쓰기 데이터를 위한 버퍼의 공간과 내부 데이터 구조에 대한 추가 공간이 필요합니다.
입력 및 출력 버퍼 크기는 권고입니다. 명명된 파이프의 각 끝에 예약된 실제 버퍼 크기는 시스템 기본값, 시스템 최소값 또는 최대값 또는 다음 할당 경계로 반올림된 지정된 크기입니다. 지정된 버퍼 크기는 프로세스에 페이지가 없는 풀이 부족하지 않고 일반적인 요청을 수용할 수 있을 만큼 충분히 커야 합니다.
파이프 쓰기 작업이 발생할 때마다 시스템은 먼저 파이프 쓰기 할당량에 대해 메모리를 충전하려고 시도합니다. 나머지 파이프 쓰기 할당량이 요청을 충족하기에 충분하면 쓰기 작업이 즉시 완료됩니다. 나머지 파이프 쓰기 할당량이 너무 작아서 요청을 처리할 수 없는 경우 시스템은 프로세스에 예약된 비페이징 풀을 사용하여 데이터를 수용하도록 버퍼를 확장하려고 합니다. 추가 버퍼 할당량을 해제할 수 있도록 파이프에서 데이터를 읽을 때까지 쓰기 작업이 차단됩니다. 따라서 지정된 버퍼 크기가 너무 작으면 시스템은 필요에 따라 버퍼를 증가하지만 단점은 작업이 차단된다는 것입니다. 작업이 겹치면 시스템 스레드가 차단됩니다. 그렇지 않으면 애플리케이션 스레드가 차단됩니다.
명명된 파이프에서 사용하는 리소스를 해제하려면 애플리케이션은 더 이상 필요하지 않을 때 항상 핸들을 닫아야 하며, CloseHandle 함수를 호출하거나 instance 핸들과 연결된 프로세스가 종료될 때 수행됩니다. 명명된 파이프의 instance 연결된 핸들이 둘 이상 있을 수 있습니다. 명명된 파이프의 instance 명명된 파이프의 instance 대한 마지막 핸들이 닫혀 있으면 항상 삭제됩니다.
Windows 10 버전 1709: 파이프는 앱 컨테이너 내에서만 지원됩니다. 즉, 한 UWP 프로세스에서 동일한 앱의 일부인 다른 UWP 프로세스까지 지원됩니다. 또한 명명된 파이프는 파이프 이름에 대한 구문을 \\.\pipe\LOCAL\ 사용해야 합니다.
예제
예제는 다중 스레드 파이프 서버를 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 2000 Professional [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows 2000 Server [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | winbase.h(Windows.h 포함) |
| 라이브러리 | Kernel32.lib |
| DLL | Kernel32.dll |
참고 항목
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기