php_stream_cast

(no version information, might be only in CVS)

php_stream_cast -- Converte um fluxo para uma outra forma, como FILE* ou socket

Descrição

int php_stream_cast ( php_stream * stream, int castas, void ** ret, int flags )

php_stream_cast() tenta converter stream em um recurso indicado por castas. Se ret for NULL, o fluxo é verificado para descobrir de tal conversão é possível, sem realizar de fato a conversão (no entanto, algum estado interno do fluxo *pode* ser alterado nesse caso). Se flags tiver o valor REPORT_ERRORS, uma mensagem de erro será mostrada se algum erro ocorrer durante a conversão.

Nota: Essa função retorna SUCCESS caso tenha sucesso ou FAILURE se falhar. Esteja avisado que você deve compara explicitamente o valor de retorno com SUCCESS ou FAILURE devido aos valores que essas constantes tem. Uma expressão booleana simples não será interpretada como você deseja.

Tabela 63-1. Tipos de recursos para castas

ValorSignificado
PHP_STREAM_AS_STDIOPede um ANSI FILE* que representa um fluxo
PHP_STREAM_AS_FDPede um descritor de arquivo POSIX que representa o fluxo
PHP_STREAM_AS_SOCKETDPede um descritor de socket de rede que representa o fluxo

Além dos tipos de recursos básicos acima, o processo de conversão podem ser alterados usando as seguintes opções usando o operador OR para combinar o tipo de recurso com um ou mais dos seguintes valores:

Tabela 63-2. Tipos de recursos para castas

ValorSignificado
PHP_STREAM_CAST_TRY_HARDTenta o máximo possível, ao custo de recursos adicionais, para assegurar-se que a conversão tenha sucesso
PHP_STREAM_CAST_RELEASEInforma a API de fluxos que outro código (possivelmente uma biblioteca de terceiros) será responsável por fechar o o fluxo. Isso causa que stream seja fechado de tal maneira que o handle abaixo é preservado e retornado em ret. Se essa função tiver sucesso, stream deve ser considerado fechado e não deve ser usado após disso.

Nota: Se seu sistema suportar fopencookie() (sistemas usando glibc 2 ou superior), a API de fluxos sempre será capaz de sintetizar um ponteiro ANSI FILE* para qualquer fluxo. Enquanto isso é tremendamente útil para passar qualquer fluxo do PHP para qualquer biblioteca de terceiros, tal comportamento não é portável. Você deve considerar as implicações de portabilidade antes de distribuir sua extensão. Se a síntese gerada pela função fopencookie não for desejável, você eve pedir ao fluxo para ver se ele suporta nativamente FILE* usando a função php_stream_is().

Nota: Se você pedir um fluxo baseado em socket para um FILE*, a API de fluxos usará fdopen() para criá-lo para você. Esteja avisado que fazer isso pode causar que os dados que estavam no buffer na camada de fluxos sejam perdidos se você misturar chamadas da API de fluxos com chamadas da ANSI stdio.

Veja também php_stream_is() e php_stream_can_cast().