캡슐

이 객체 사용에 대한 자세한 정보는 확장 모듈을 위한 C API 제공하기를 참조하십시오.

버전 3.1에 추가.

PyCapsule

이 PyObject의 서브 형은 불투명한 값을 나타내며, 파이썬 코드를 통해 다른 C 코드로 불투명한 값(void* 포인터로)을 전달해야 하는 C 확장 모듈에 유용합니다. 이것은 한 모듈에서 정의된 C 함수 포인터를 다른 모듈에서 사용할 수 있게 만드는 데 종종 사용되므로, 일반 임포트 메커니즘을 사용하여 동적으로 로드된 모듈에 정의된 C API에 액세스할 수 있습니다.

PyCapsule_Destructor

캡슐에 대한 파괴자(destructor) 콜백 형. 이렇게 정의됩니다:

typedef void (*PyCapsule_Destructor)(PyObject *);

PyCapsule_Destructor 콜백의 의미는 PyCapsule_New()를 참조하십시오.

int PyCapsule_CheckExact(PyObject *p)

인자가 PyCapsule이면 참을 돌려줍니다. 이 함수는 항상 성공합니다.

PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)

Return value: New reference.

pointer를 캡슐화하는 PyCapsule을 만듭니다. pointer 인자는 NULL이 아닐 수도 있습니다.

실패하면, 예외를 설정하고 NULL을 반환합니다.

name 문자열은 NULL 이나 유효한 C 문자열에 대한 포인터일 수 있습니다. NULL이 아니면, 이 문자열은 캡슐보다 오래 유지되어야 합니다. (destructor 내부에서 해제할 수는 있습니다.)

destructor 인자가 NULL이 아니면, 캡슐이 파괴될 때 캡슐을 인자로 호출됩니다.

이 캡슐을 모듈의 어트리뷰트로 저장하려면, name을 modulename.attributename로 지정해야 합니다. 이렇게 하면 다른 모듈이 PyCapsule_Import()를 사용하여 캡슐을 임포트 할 수 있습니다.

void* PyCapsule_GetPointer(PyObject *capsule, const char *name)

캡슐에 저장된 pointer를 가져옵니다. 실패하면, 예외를 설정하고 NULL을 반환합니다.

name 매개 변수는 캡슐에 저장된 이름과 정확하게 비교되어야 합니다. 캡슐에 저장된 이름이 NULL이면, 전달된 name도 NULL 이어야 합니다. 파이썬은 C 함수 strcmp()를 사용하여 캡슐 이름을 비교합니다.

PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)

캡슐에 저장된 현재 파괴자를 반환합니다. 실패하면, 예외를 설정하고 NULL을 반환합니다.

캡슐이 NULL 파괴자를 갖는 것은 합법적입니다. 이것은 NULL 반환 코드를 다소 모호하게 만듭니다; 명확히 하려면 PyCapsule_IsValid() 나 PyErr_Occurred()를 사용하십시오.

void* PyCapsule_GetContext(PyObject *capsule)

캡슐에 저장된 현재 컨텍스트를 반환합니다. 실패하면, 예외를 설정하고 NULL을 반환합니다.

캡슐이 NULL 컨텍스트를 갖는 것은 합법적입니다. 이것은 NULL 반환 코드를 다소 모호하게 만듭니다; 명확히 하려면 PyCapsule_IsValid() 나 PyErr_Occurred()를 사용하십시오.

const char* PyCapsule_GetName(PyObject *capsule)

캡슐에 저장된 현재 이름을 반환합니다. 실패하면, 예외를 설정하고 NULL을 반환합니다.

캡슐이 NULL 이름을 갖는 것은 합법적입니다. 이것은 NULL 반환 코드를 다소 모호하게 만듭니다; 명확히 하려면 PyCapsule_IsValid() 나 PyErr_Occurred()를 사용하십시오.

void* PyCapsule_Import(const char *name, int no_block)

모듈의 캡슐 어트리뷰트에서 C 객체에 대한 포인터를 임포트 합니다. name 매개 변수는 module.attribute 처럼 어트리뷰트의 전체 이름을 지정해야 합니다. 캡슐에 저장된 name은, 이 문자열과 정확히 일치해야 합니다. no_block이 참이면, 블록하지 않고 모듈을 임포트 합니다 (PyImport_ImportModuleNoBlock()를 사용해서). no_block이 거짓이면, 모듈을 평범하게 임포트 합니다 (PyImport_ImportModule()을 사용해서).

성공하면 캡슐의 내부 pointer를 반환합니다. 실패하면, 예외를 설정하고 NULL를 반환합니다.

int PyCapsule_IsValid(PyObject *capsule, const char *name)

capsule이 유효한 캡슐인지를 판단합니다. 유효한 캡슐은 NULL이 아니며, PyCapsule_CheckExact()를 통과하고, NULL이 아닌 포인터가 저장되며, 내부 이름이 name 매개 변수와 일치합니다. (캡슐 이름을 비교하는 방법에 대한 정보는 PyCapsule_GetPointer()를 참조하십시오.)

즉, PyCapsule_IsValid()가 참값을 반환하면, 모든 접근자(PyCapsule_Get()으로 시작하는 모든 함수)에 대한 호출이 성공함이 보장됩니다.

객체가 유효하고 전달된 이름과 일치하면 0이 아닌 값을 반환합니다. 그렇지 않으면 0을 반환합니다. 이 함수는 실패하지 않습니다.

int PyCapsule_SetContext(PyObject *capsule, void *context)

capsule 내부의 컨텍스트 포인터를 context로 설정합니다.

성공하면 0을 반환합니다. 실패하면 0이 아닌 값을 반환하고 예외를 설정합니다.

int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)

capsule 내부의 파괴자를 destructor로 설정합니다.

성공하면 0을 반환합니다. 실패하면 0이 아닌 값을 반환하고 예외를 설정합니다.

int PyCapsule_SetName(PyObject *capsule, const char *name)

capsule 내부의 이름을 name으로 설정합니다. NULL이 아니면, 이름은 캡슐보다 오래 유지되어야 합니다. 캡슐에 저장된 이전 name이 NULL이 아니면, 이를 해제하려고 시도하지 않습니다.

성공하면 0을 반환합니다. 실패하면 0이 아닌 값을 반환하고 예외를 설정합니다.

int PyCapsule_SetPointer(PyObject *capsule, void *pointer)

capsule 내부의 void 포인터를 pointer로 설정합니다. 포인터는 NULL이 아닐 수 있습니다.

성공하면 0을 반환합니다. 실패하면 0이 아닌 값을 반환하고 예외를 설정합니다.