TSPI_lineGetDevConfig 함수(tspi.h)

아티클
08/26/2023

TSPI_lineGetDevConfig 함수는 줄(서비스 공급자) 및 디바이스 클래스와 관련된 데이터 구조 개체를 반환하여 라인 디바이스와 일대일로 연결된 디바이스의 현재 구성을 제공합니다.

구문

LONG TSPIAPI TSPI_lineGetDevConfig(
  DWORD       dwDeviceID,
  LPVARSTRING lpDeviceConfig,
  LPCWSTR     lpszDeviceClass
);

매개 변수

dwDeviceID

구성할 줄 디바이스입니다.

lpDeviceConfig

연결된 디바이스의 디바이스 구성 구조가 반환되는 VARSTRING 형식의 데이터 구조에 대한 포인터입니다. 요청이 성공적으로 완료되면 서비스 공급자는 이 데이터 구조를 디바이스 구성으로 채웁니다. VARSTRING 구조체의 dwStringFormat 멤버는 STRINGFORMAT_BINARY 설정해야 합니다. lpDeviceConfig 매개 변수가 가리키는 VARSTRING 구조체의 dwTotalSize 멤버가 구조체의 고정 부분 크기보다 크거나 같으면 서비스 공급자는 dwNeededSize 멤버를 필요한 크기로 설정하고 0을 반환합니다.

lpszDeviceClass

구성이 요청된 디바이스의 디바이스 클래스를 지정하는 null로 끝나는 유니코드 문자열에 대한 포인터입니다. 유효한 디바이스 클래스 문자열은 줄 디바이스에 적용될 때 TSPI_lineGetID 함수에 대해 지정된 문자열과 동일합니다(dwSelect 에는 LINECALLSELECT_LINE 값이 있습니다).

반환 값

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

LINEERR_INVALDEVICECLASS, LINEERR_NOMEM, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_OPERATIONFAILED, LINEERR_NODRIVER, LINEERR_RESOURCEUNAVAIL.

설명

호출 상태는 디바이스별로 다릅니다.

이 함수는 라인 디바이스와 일대일로 연결된 디바이스의 구성을 지정하는 서비스 공급자에서 데이터 구조를 검색하는 데 사용할 수 있습니다. lpszDeviceClass 매개 변수는 구성을 검색할 여러 디바이스 클래스 중에서 선택할 수 있습니다. 지원되는 클래스 집합은 디바이스가 라인 디바이스와 일대일로 일치하는 클래스로 제한됩니다. 일반적인 디바이스 클래스에 대한 자세한 내용은 TSPI 디바이스 클래스를 참조하세요.

서비스 공급자는 일반적으로 이 함수에서 tapi/line 디바이스 클래스를 허용해야 합니다. 이 줄의 주소 목록, 주소에 해당하는 COMM 포트와 같은 물리적 하드웨어 디바이스 목록, 최대 동시 호출 수(구성 가능한 경우) 등과 같은 "줄" scope 있는 매개 변수를 검색합니다.

일반적으로 이 함수는 일반적으로 특정 호출 또는 특정 주소에 적용되므로 mci waveaudio, 하위 수준 웨이브 또는 datamodem 디바이스 클래스와 같은 미디어 관련 디바이스 클래스를 허용하지 않습니다. 회선 디바이스당 둘 이상이 있을 수 있으므로 이 함수의 줄 디바이스 식별자 매개 변수로만 특정 호출 또는 주소를 식별하는 것은 모호합니다. 초기 기본값 등과 같이 전체 줄 디바이스 scope 적용되는 클래스 구성 정보가 있는 경우 호출별 또는 주소별 디바이스 클래스에는 예외가 있을 수 있습니다.

호출별 및 주소별 디바이스 클래스에 대한 예외적인 지원이 이 함수에서 제한된 값만 지원되는 데는 여러 가지 이유가 있습니다. 첫째, 이러한 클래스는 다중 주소/다중 호출 서비스 공급자에서 모호할 수 있으므로 서비스 공급자의 하위 집합만 지원합니다. 애플리케이션은 이 함수에 이러한 클래스를 포함할 때 디바이스별 종속성을 추가할 가능성이 없습니다. 둘째, 낮은 수준의 전송 API 측면에서 전화 접속 파일 시스템 액세스와 같은 상위 수준 프로토콜을 구현하는 상위 수준 미디어 "클래스"가 등장함에 따라 이러한 클래스에 대한 구성은 "클래스" scope 대신 "instance" scope 경향이 있습니다. 상위 수준 미디어 API는 호출별 또는 주소별 인스턴스를 구성하기 위해 자체 함수를 제공해야 합니다.

이 함수가 지원하는 디바이스 및 디바이스 클래스의 종류에 관계없이 영구 및 임시의 두 가지 구성 정보에 영향을 줄 수 있습니다. 영구 정보는 줄의 다른 "열기"와 서비스 공급자 자체의 다른 "inits"에서도 유지됩니다. 임시 정보는 줄의 고유한 "열기" 내에서만 유지됩니다. 줄을 닫으면 TSPI_lineSetDevConfig 통해 검색되거나 설정된 이러한 임시 정보는 기본값 또는 정의되지 않은 값으로 되돌리기 수 있습니다. 호출자는 TSPI_lineOpen,TSPI_lineConfigDialog, TSPI_lineGetDevConfig 같은 시퀀스로만 임시 구성을 안정적으로 검색할 수 있습니다. 호출자는 TSPI_lineOpen, TSPI_lineSetDevConfig 같은 시퀀스를 통해 이러한 시퀀스에서 검색된 임시 구성 정보를 안정적으로 설정할 수 있습니다. 구성의 임시 부분은 다음 TSPI_lineConfigDialog, TSPI_lineSetDevConfig또는TSPI_lineClose 때까지만 안정적으로 유지됩니다. 서비스 공급자는 구성의 영구 부분(일반적으로 .ini 파일)을 저장하고 서비스 공급자가 초기화될 때마다 다시 로드해야 합니다.

이 함수에서 반환하는 구조 내에 포함된 데이터의 정확한 형식은 줄 및 디바이스 클래스 API에만 적용되며 문서화되지 않았으며 정의되지 않았습니다. 이 함수에서 반환된 구조체는 애플리케이션에서 직접 액세스하거나 조작할 수 없지만, 그대로 저장하고 나중에 TSPI_lineSetDevConfig 설정 복원에만 사용할 수 있습니다. 구조는 동일한 디바이스 클래스에서도 반드시 다른 디바이스에 전달할 수 없습니다(일부 경우에 작동할 수 있지만 보장되지는 않음). 서비스 공급자는 호환되지 않는 정보를 전달하는 클라이언트 애플리케이션으로 인한 오류를 막기 위해 일관성을 검사할 수 있도록 데이터 구조에 항목을 배치해야 합니다.