CreateNamedPipeA 함수(winbase.h)
명명된 파이프의 인스턴스를 만들고 후속 파이프 작업에 대한 핸들을 반환합니다. 명명된 파이프 서버 프로세스는 이 함수를 사용하여 명명된 특정 파이프의 첫 번째 인스턴스를 만들고 기본 특성을 설정하거나 기존 명명된 파이프의 새 인스턴스를 만듭니다.
통사론
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 이외의 항목을 지정하면 함수가 실패합니다.
이 매개 변수는 다음 파이프 액세스 모드 중 하나를 지정해야 합니다. 파이프의 각 인스턴스에 대해 동일한 모드를 지정해야 합니다.
| 모드 | 의미 |
|---|---|
|
파이프는 양방향입니다. 서버 및 클라이언트 프로세스는 파이프에서 읽고 파이프에 쓸 수 있습니다. 이 모드는 서버에 파이프에 대한 GENERIC_READ 및 GENERIC_WRITE 액세스와 동등한 권한을 부여합니다. 클라이언트는 CreateFile 함수를 사용하여 파이프에 연결할 때 GENERIC_READ 또는 GENERIC_WRITE또는 둘 다를 지정할 수 있습니다. |
|
파이프의 데이터 흐름은 클라이언트에서 서버로만 이동합니다. 이 모드는 서버에 파이프에 대한 GENERIC_READ 액세스와 동등한 권한을 부여합니다. 클라이언트는 파이프에 연결할 때 GENERIC_WRITE 액세스를 지정해야 합니다. 클라이언트가 |
|
파이프의 데이터 흐름은 서버에서 클라이언트로만 이동합니다. 이 모드는 서버에 파이프에 대한 GENERIC_WRITE 액세스와 동등한 권한을 부여합니다. 클라이언트는 파이프에 연결할 때 GENERIC_READ 액세스를 지정해야 합니다. 클라이언트가 SetNamedPipeHandleState 함수를 호출하여 파이프 설정을 변경해야 하는 경우 클라이언트는 파이프에 연결할 때 GENERIC_READ 및 FILE_WRITE_ATTRIBUTES 액세스를 지정해야 합니다. |
이 매개 변수에는 쓰기 및 겹치는 모드를 사용하도록 설정하는 다음 플래그 중 하나 이상이 포함될 수도 있습니다. 이러한 모드는 동일한 파이프의 다른 인스턴스에 대해 다를 수 있습니다.
| 모드 | 의미 |
|---|---|
|
이 플래그를 사용하여 파이프의 여러 인스턴스를 만들려고 하면 첫 번째 인스턴스를 만드는 데 성공하지만 ERROR_ACCESS_DENIED다음 인스턴스를 만들지 못합니다. |
|
쓰기 모드를 사용할 수 있습니다. 이 모드는 바이트 형식 파이프에 대한 쓰기 작업에만 영향을 줍니다. 그런 다음 클라이언트 및 서버 프로세스가 서로 다른 컴퓨터에 있는 경우에만 적용됩니다. 이 모드를 사용하도록 설정하면 기록된 데이터가 네트워크를 통해 전송되고 원격 컴퓨터의 파이프 버퍼에 있게 될 때까지 명명된 파이프에 쓰는 함수가 반환되지 않습니다. 이 모드를 사용하도록 설정하지 않으면 최소 바이트 수가 누적되거나 최대 시간이 경과할 때까지 데이터를 버퍼링하여 네트워크 작업의 효율성을 향상시킵니다. |
|
겹치는 모드를 사용할 수 있습니다. 이 모드를 사용하도록 설정하면 완료하는 데 상당한 시간이 걸릴 수 있는 읽기, 쓰기 및 연결 작업을 수행하는 함수가 즉시 반환될 수 있습니다. 이 모드를 사용하면 작업을 시작한 스레드가 백그라운드에서 시간이 많이 걸리는 작업을 실행하는 동안 다른 작업을 수행할 수 있습니다. 예를 들어 겹치는 모드에서 스레드는 파이프의 여러 인스턴스에서 동시 입력 및 출력(I/O) 작업을 처리하거나 동일한 파이프 핸들에서 동시 읽기 및 쓰기 작업을 수행할 수 있습니다. 겹치는 모드를 사용할 수 없는 경우 파이프 핸들에서 읽기, 쓰기 및 연결 작업을 수행하는 함수는 작업이 완료될 때까지 반환되지 않습니다. ReadFileEx 및 WriteFileEx 함수는 겹치는 모드의 파이프 핸들에서만 사용할 수 있습니다. ReadFile, WriteFile, ConnectNamedPipe및 TransactNamedPipe 함수는 동기적으로 또는 겹치는 작업으로 실행할 수 있습니다. |
이 매개 변수는 다음 보안 액세스 모드의 조합을 포함할 수 있습니다. 이러한 모드는 동일한 파이프의 다른 인스턴스에 대해 다를 수 있습니다.
[in] dwPipeMode
파이프 모드입니다.
dwPipeMode 다음 표에 나열된 플래그 또는 0 이외의 항목을 지정하면 함수가 실패합니다.
다음 형식 모드 중 하나를 지정할 수 있습니다. 파이프의 각 인스턴스에 대해 동일한 형식 모드를 지정해야 합니다.
| 모드 | 의미 |
|---|---|
|
데이터는 바이트 스트림으로 파이프에 기록됩니다. 이 모드는 PIPE_READMODE_MESSAGE 사용할 수 없습니다. 파이프는 다른 쓰기 작업 중에 작성된 바이트를 구분하지 않습니다. |
|
데이터는 메시지 스트림으로 파이프에 기록됩니다. 파이프는 각 쓰기 작업 중에 작성된 바이트를 메시지 단위로 처리합니다. GetLastError 함수는 메시지를 완전히 읽지 않으면 ERROR_MORE_DATA 반환합니다. 이 모드는 PIPE_READMODE_MESSAGE 또는 PIPE_READMODE_BYTE함께 사용할 수 있습니다. |
다음 읽기 모드 중 하나를 지정할 수 있습니다. 동일한 파이프의 다른 인스턴스는 다른 읽기 모드를 지정할 수 있습니다.
다음 대기 모드 중 하나를 지정할 수 있습니다. 동일한 파이프의 다른 인스턴스는 서로 다른 대기 모드를 지정할 수 있습니다.
| 모드 | 의미 |
|---|---|
|
차단 모드를 사용할 수 있습니다. 파이프 핸들이 ReadFile, WriteFile또는 ConnectNamedPipe 함수에 지정되면 읽을 데이터가 있거나 모든 데이터가 기록되거나 클라이언트가 연결될 때까지 작업이 완료되지 않습니다. 이 모드를 사용하면 클라이언트 프로세스가 작업을 수행하기 위해 일부 상황에서 무기한 대기하는 것을 의미할 수 있습니다. |
|
차단 해제 모드를 사용할 수 있습니다. 이 모드에서는 ReadFile, 비 차단 모드는 Microsoft LAN Manager 버전 2.0과의 호환성을 위해 지원되며 명명된 파이프를 사용하여 비동기 I/O를 달성하는 데 사용하면 안 됩니다. 비동기 파이프 I/O에 대한 자세한 내용은 동기 및 겹치는 입력 및 출력참조하세요. |
다음 원격 클라이언트 모드 중 하나를 지정할 수 있습니다. 동일한 파이프의 다른 인스턴스는 서로 다른 원격 클라이언트 모드를 지정할 수 있습니다.
| 모드 | 의미 |
|---|---|
|
원격 클라이언트의 연결을 수락하고 파이프의 보안 설명자에 대해 확인할 수 있습니다. |
|
원격 클라이언트의 연결은 자동으로 거부됩니다. |
[in] nMaxInstances
이 파이프에 대해 만들 수 있는 최대 인스턴스 수입니다. 파이프의 첫 번째 인스턴스는 이 값을 지정할 수 있습니다. 파이프의 다른 인스턴스에 대해 동일한 번호를 지정해야 합니다. 허용되는 값은 1부터 PIPE_UNLIMITED_INSTANCES(255) 범위입니다.
이 매개 변수가 PIPE_UNLIMITED_INSTANCES경우 만들 수 있는 파이프 인스턴스 수는 시스템 리소스의 가용성에 의해서만 제한됩니다. nMaxInstances
[in] nOutBufferSize
출력 버퍼에 대해 예약할 바이트 수입니다. 명명된 파이프 버퍼 크기 조정에 대한 자세한 내용은 다음 설명 섹션을 참조하세요.
[in] nInBufferSize
입력 버퍼에 대해 예약할 바이트 수입니다. 명명된 파이프 버퍼 크기 조정에 대한 자세한 내용은 다음 설명 섹션을 참조하세요.
[in] nDefaultTimeOut
WaitNamedPipe 함수가 NMPWAIT_USE_DEFAULT_WAIT지정하는 경우 기본 제한 시간 값(밀리초)입니다. 명명된 파이프의 각 인스턴스는 동일한 값을 지정해야 합니다.
값이 0이면 기본 제한 시간이 50밀리초입니다.
[in, optional] lpSecurityAttributes
명명된 새 파이프에 대한 보안 설명자를 지정하고 자식 프로세스가 반환된 핸들을 상속할 수 있는지 여부를 결정하는 SECURITY_ATTRIBUTES 구조체에 대한 포인터입니다.
반환 값
함수가 성공하면 반환 값은 명명된 파이프 인스턴스의 서버 끝에 대한 핸들입니다.
함수가 실패하면 반환 값이 INVALID_HANDLE_VALUE. 확장 오류 정보를 얻으려면 GetLastError호출합니다.
발언
CreateNamedPipe사용하여 명명된 파이프의 인스턴스를 만들려면 사용자에게 명명된 파이프 개체에 대한 FILE_CREATE_PIPE_INSTANCE 액세스 권한이 있어야 합니다. 명명된 새 파이프를 만드는 경우 보안 특성 매개 변수의 ACL(액세스 제어 목록)은 명명된 파이프에 대한 임의 액세스 제어를 정의합니다.
명명된 파이프의 모든 인스턴스는 동일한 파이프 유형(바이트 형식 또는 메시지 형식), 파이프 액세스(이중, 인바운드 또는 아웃바운드), 인스턴스 수 및 제한 시간 값을 지정해야 합니다. 다른 값을 사용하면 이 함수가 실패하고 GetLastError
클라이언트 프로세스는 CreateFile 또는 CallNamedPipe 함수를 사용하여 명명된 파이프에 연결합니다. 서버 쪽이 메시지 모드인 경우에도 명명된 파이프의 클라이언트 쪽이 바이트 모드에서 시작됩니다. 데이터 수신 문제를 방지하려면 클라이언트 쪽도 메시지 모드로 설정합니다. 파이프 모드를 변경하려면 파이프 클라이언트가 GENERIC_READFILE_WRITE_ATTRIBUTES 액세스 권한이 있는 읽기 전용 파이프를 열어야 합니다.
파이프 서버는 파이프 클라이언트가 시작될 때까지 읽기 차단 작업을 수행해서는 안 됩니다. 그렇지 않으면 경합 상태가 발생할 수 있습니다. 이는 일반적으로 C 런타임과 같은 초기화 코드가 상속된 핸들을 잠그고 검사해야 하는 경우에 발생합니다.
명명된 파이프를 만들 때마다 시스템은 커널에서 사용하는 실제 메모리인 비페이지 풀을 사용하여 인바운드 및/또는 아웃바운드 버퍼를 만듭니다. 만들 수 있는 파이프 인스턴스(스레드 및 프로세스와 같은 개체)의 수는 사용 가능한 비페이지 풀에 의해 제한됩니다. 각 읽기 또는 쓰기 요청에는 읽기 또는 쓰기 데이터에 대한 버퍼의 공간과 내부 데이터 구조에 대한 추가 공간이 필요합니다.
입력 및 출력 버퍼 크기는 권고입니다. 명명된 파이프의 각 끝에 예약된 실제 버퍼 크기는 시스템 기본값, 시스템 최소값 또는 최대값 또는 다음 할당 경계로 반올림된 지정된 크기입니다. 지정된 버퍼 크기는 프로세스가 페이지가 지정되지 않은 풀이 부족하지 않을 정도로 작지만 일반적인 요청을 수용할 수 있을 만큼 커야 합니다.
파이프 쓰기 작업이 발생할 때마다 시스템은 먼저 파이프 쓰기 할당량에 대해 메모리를 충전하려고 시도합니다. 나머지 파이프 쓰기 할당량이 요청을 수행하기에 충분하면 쓰기 작업이 즉시 완료됩니다. 나머지 파이프 쓰기 할당량이 너무 작아서 요청을 처리할 수 없는 경우 시스템은 프로세스에 예약된 비페이징 풀을 사용하여 데이터를 수용하도록 버퍼를 확장하려고 합니다. 추가 버퍼 할당량을 해제할 수 있도록 파이프에서 데이터를 읽을 때까지 쓰기 작업이 차단됩니다. 따라서 지정된 버퍼 크기가 너무 작으면 시스템에서 필요에 따라 버퍼를 증가하지만 단점은 작업이 차단된다는 것입니다. 작업이 겹치면 시스템 스레드가 차단됩니다. 그렇지 않으면 애플리케이션 스레드가 차단됩니다.
명명된 파이프에서 사용하는 리소스를 해제하려면 애플리케이션은 더 이상 필요하지 않을 때 항상 핸들을 닫아야 합니다. 이 작업은 CloseHandle 함수를 호출하거나 인스턴스 핸들과 연결된 프로세스가 종료될 때 수행됩니다. 명명된 파이프의 인스턴스에는 둘 이상의 핸들이 연결되어 있을 수 있습니다. 명명된 파이프의 인스턴스는 명명된 파이프의 인스턴스에 대한 마지막 핸들이 닫혀 있을 때 항상 삭제됩니다.
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 |
참고 항목
ConnectNamedPipe
CreateFile
파이프 함수
ReadFile
ReadFileEx
transactNamedPipe
waitNamedPipe
WriteFile
WriteFileEx