lineConfigDialogEdit 함수(tapi.h)

아티클
03/08/2023

lineConfigDialogEdit 함수를 사용하면 지정된 줄 디바이스의 공급자가 대화 상자(애플리케이션의 hwndOwner에 연결됨)를 표시하여 사용자가 줄 디바이스와 관련된 매개 변수를 구성할 수 있습니다.

구문

LONG lineConfigDialogEdit(
  DWORD        dwDeviceID,
  HWND         hwndOwner,
  LPCSTR       lpszDeviceClass,
  LPVOID const lpDeviceConfigIn,
  DWORD        dwSize,
  LPVARSTRING  lpDeviceConfigOut
);

매개 변수

dwDeviceID

구성할 라인 디바이스의 식별자입니다.

hwndOwner

대화 상자를 연결할 창에 대한 핸들입니다. 함수 중에 만든 창에 소유자 창이 없어야 함을 나타내는 NULL 일 수 있습니다.

lpszDeviceClass

디바이스 클래스 이름을 식별하는 null로 끝나는 문자열에 대한 포인터입니다. 이 디바이스 클래스를 사용하면 애플리케이션이 해당 디바이스 클래스에 적용할 수 있는 구성 정보의 특정 하위 화면을 선택할 수 있습니다. 이 매개 변수는 선택 사항이며 NULL 또는 빈 상태로 둘 수 있습니다. 이 경우 가장 높은 수준의 구성이 선택됩니다.

lpDeviceConfigIn

VARSTRING 구조체의 변수 부분에서 lineGetDevConfig(또는 lineConfigDialogEdit의 이전 호출)에서 반환된 불투명 구성 데이터 구조체에 대한 포인터입니다.

dwSize

lpDeviceConfigIn이 가리키는 구조체의 바이트 수입니다. 이 값은 lineGetDevConfig 또는 lineConfigDialogEdit의 이전 호출에서 반환된 VARSTRING 구조체의 dwStringSize 멤버에 반환됩니다.

lpDeviceConfigOut

디바이스 구성 구조가 반환되는 VARSTRING 유형의 메모리 위치에 대한 포인터입니다. 요청이 성공적으로 완료되면 이 위치는 디바이스 구성으로 채워집니다. VARSTRING 구조체의 dwStringFormat 멤버는 STRINGFORMAT_BINARY 설정됩니다. lineGetDevConfig(또는 lineConfigDialogEdit의 향후 호출)를 호출하기 전에 애플리케이션은 정보를 반환하기 위해 TAPI에 사용할 수 있는 메모리 양을 나타내도록 이 구조체의 dwTotalSize 멤버를 설정해야 합니다.

반환 값

요청이 성공하면 0을 반환하고 오류가 발생하면 음수 오류 번호를 반환합니다. 가능한 반환 값은 다음과 같습니다.

LINEERR_BADDEVICEID, LINEERR_OPERATIONFAILED, LINEERR_INVALDEVICECLASS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM, LINEERR_NODEVICE.

설명

LINEERR_STRUCTURETOOSMALL 반환되는 경우 lpDeviceConfigOut에서 가리키는 VARSTRING 구조체의 dwTotalSize 멤버는 전체 구성 구조를 포함하기에 충분한 메모리를 지정하지 않습니다. dwNeededSize 멤버가 필요한 금액으로 설정되었습니다. 공간 부족으로 인해 반환할 수 없는 정보에 사용자 항목이 반영되는 한 해당 편집 내용은 손실됩니다. 따라서 애플리케이션은 구성 구조를 반환하기 위해 디바이스 클래스에 필요할 수 있는 최대 공간을 할당해야 합니다(자세한 내용은 TAPI 디바이스 클래스 참조).

lineConfigDialogEdit 함수를 사용하면 서비스 공급자가 모달 대화 상자(애플리케이션의 hwndOwner에 연결됨)를 표시하여 사용자가 dwDeviceID로 지정된 줄과 관련된 매개 변수를 구성할 수 있습니다.

lpszDeviceClass 매개 변수를 사용하면 애플리케이션에서 사용자가 관심이 있는 디바이스 클래스에 적용할 수 있는 구성 정보의 특정 하위 화면을 선택할 수 있습니다. 허용되는 문자열은 lineGetID와 동일합니다. 예를 들어 줄이 Comm API를 지원하는 경우 "COMM"을 lpszDeviceClass 로 전달하면 공급자가 Comm과 관련된 매개 변수를 표시합니다(또는 적어도 다단계 구성 대화 상자 체인의 해당 지점에서 시작하므로 사용자가 관심 있는 매개 변수를 찾기 위해 "발굴"할 필요가 없음).

lpszDeviceClass 매개 변수는 "tapi/line" , "" 또는 NULL이므로 공급자가 줄에 대해 가장 높은 수준의 구성을 표시합니다.

이 함수와 lineConfigDialog 의 차이점은 편집할 매개 변수의 원본과 편집 결과입니다. lineConfigDialog에서 편집된 매개 변수는 현재 디바이스에서 사용 중인 매개 변수(또는 다음 호출에서 사용하도록 설정됨)이며 변경된 모든 변경 내용은 활성 연결에 즉각적인 영향을 줍니다. 또한 애플리케이션은 lineGetDevConfig를 사용하여 lineConfigDialog에서 매개 변수 변경 결과를 가져와야 합니다. lineConfigDialogEdit를 사용하면 편집할 매개 변수가 애플리케이션에서 전달되고 결과는 활성 연결에 영향을 주지 않고 애플리케이션으로 반환됩니다. 편집 결과는 이 함수와 함께 반환되며 애플리케이션은 lineGetDevConfig를 호출할 필요가 없습니다. 따라서 lineConfigDialogEdit 를 사용하면 사용자가 활성 호출에 영향을 주지 않고 향후 호출에 대한 매개 변수를 설정할 수 있는 기능을 애플리케이션에 제공할 수 있습니다. 그러나 이 함수의 출력을 lineSetDevConfig 에 전달하여 현재 호출 또는 다음 호출에 영향을 줄 수 있습니다.