nsIChannel

Imagen:traduccion-pendiente.png Esta página está traduciéndose a partir del artículo nsIChannel, razón por la cual puede haber algunos errores sintácticos o partes sin traducir. Puedes colaborar continuando con la traducción

La interfaz nsIChannel permite a los clientes construir peticiones "GET" para protocolos específicos y manejarlos de forma uniforme.

nsIChannel is defined in https://mxr.mozilla.org/mozilla/sourc...nsIChannel.idl .

Una vez que se crea un canal (via nsIIOService::newChannel), pueden presentarse parámetros para esa petición usando los atributos de canal, o poniéndose en cola (QI'ing) de una subclase de nsIchannel para los parámetros específicos del protocolo. Entonces, puede buscarse la URI llamando nsIChannel::open o nsIChannel::asyncOpen. Después de que una petición se ha completado, el canal está aún disponible para acceder a resultados específicos del protocolo. Por ejemplo, poniéndose en cola (QI'ing) a nsIHttpChannel permite que se puedan leer las correspondientes cabeceras de respuesta de una transacción http.

Métodos

open()

nsIInputStream open();

Abre un canal de forma síncrona.

@return blocking input stream to the channel's data.

NOTA: las implementaciones nsIChannel no requieren implementar este método. Aún más, ya que este método puede llegar a bloquear el proceso de la llamada, no debería usarse en el transcurso del proceso de eventos UI.

NOTA: Las implementaciones deberían devolver NS_ERROR_IN_PROGRESS si se re-abre el canal.

asyncOpen()

void asyncOpen(in nsIStreamListener aListener, in nsISupports aContext);

Abre este canal de forma asíncrona. Los datos son enviados al canal de escucha en cuanto están disponibles. El método de escucha es llamado en el mismo hilo en que se encuentra la operación de llamada asyncOpen y no es llamado hasta después del retorno de la función asyncOpen. Si asyncOpen devuelve con éxito, el canal prometo llamar al menos a onStartRequest y onStopRequest.

Si el objeto nsIRequest pasado al método de escucha no está en este canal, es necesario enviar una notificación onChannelRedirect antes de llamar a onStartRequest.

Si llamada de retorno del canal y del grupo de carga no ofrecen un nsIChannelEventSink al hacer la llamada a onChannelRedirect, esto es equivalente a haber llamado a onChannelRedirect.

Si asyncOpen retorna con éxito, el canal es responsable de mantenerse vivo hasta que reciba una llamada onStopRequest en la escucha o se lame a onChannelRedirect.

Las implementaciones tienen permitido añadirse por sí mismas, de forma síncrona, al grupo de carga asociado (si lo hay).

NOTA: Las implementaciones deberían devolver NS_ERROR_ALREADY_OPENED si un canal es re-abierto.

@param aListener the nsIStreamListener implementation @param aContext an opaque parameter forwarded to aListener's methods @see nsIChannelEventSink for onChannelRedirect

Atributos

Atributo	Tipo	Descripción
`originalURI`	`nsIURI`	La URI original usada para construir el canal. Esto se usa en el caso de una "resolución" de una URI re-dirigida (p.e. resolviendo un recurso: URI a archivo: URI) de forma que la URI original (antes de la redireción) esté disponible. NOTA: esto es notablemente distinto del Referer de http (URI referente) que es usualmente la página que contenía la URI original (accesible desde nsIHttpChannel).
`URI`	readonly `nsIURI`	La URI correspondienter al canal. Su valor es inmutable.
`owner`	`nsISupports`	El dueño, correspondiendo a la entidad que es responsable por este canal. Lo usa el agente de seguridad para otorgar o denegar privilegios al código cargado a través de este canal. NOTA: esto es una fuerte referencia al dueño, de forma que si este está también manteniendo una fuerte referencia al canal, hay que tener mucho cuidado de cortar explícitamente la referencia al canal.
`notificationCallbacks`	`nsIInterfaceRequestor`	Las llamadas de notificación devueltas al canal. Estas son realizadas por el cliente, que quiere ofrecer una forma de recibir notificaciones de progreso, estado o específicas del protocolo. Si este valor es NULL, la implementación del canal puede usar las llamadas devueltas a su grupo de carga. El canal también puede interrogar las llamadas desde su grupo de carga, si las notificaciones que le llegan no ofrecen el interfaz requerido. Los interfaces usualmente requeridos incluyen: nsIProgressEventSink, nsIPrompt, y nsIAuthPrompt/nsIAuthPrompt2. Cuando el canal ha terminado, no debe mantener ninguna referencia a estos objetos. NOTA: Una implementación de un canal debe tener cuidado cuando almacena ("caching") el puntero de un interfaz llamado en una notificación. Si la notificación cambia, el puntero almacenado puede ser invalido y por tanto debería ser buscado de nuevo.
`securityInfo`	readonly `nsISupports`	Información de seguridad a nivel transporte (si la hay) correspondiente al canal.
`contentType`	readonly `ACString`	El tipo MIME del contenido del canal, si está disponible. NOTA: el tipo de contenido está, a menudo, incorrectamente especificado (p.e. extensión incorrecta del archivo, tipo MIME incorrecto, tipo de documento equivocado en el servidor, etc.) y es aconsejeble que el llamante verifique los datos propiamente. Establecer contentType antes de que el canal esté abierto, da una pista al canal sobre que tipo de MIME se va a encontrar. El canal puede ignorar esta pista y decidir el tipo MIME que va a reportar. Establecer contentType despues de que onStartRequest sea llamado o despues de llamar a open(), sobre escribirá el tipo determinado por el canal. Establecer contentType en el momento entre que asyncOpen() es llamada y el momento en que se lanza onStartRequest tendrá resultados inpredecibles en este momento. El valor del atributo contentType es una cadena en minúsculas. El valor asignado a este atributo será analizado y nomalizado de la siguiente forma: 1- cualquier parámetro (delimitado con ';') será desnudado. 2- si se da un parámetro del tipo charset, su valor reemplazará el atributo contentCharset del canal. 3- el valor desnudado será convertido a minúsculas. cualquier implementación de nsIChannel debe seguir estas reglas.
`contentCharset`	readonly `ACString`	El juego de caracteres del contenido del canal si está disponible y es aplicable. Este atributo solo se aplica a datos tipo texto. El valor del atributo contentCharset es una cadena de mayúsculas y minúsculas.
`contentLength`	readonly `long`	La longitud de los datos asociados con el canal si está disponible. Un valor de -1 indica que la longitud es desconocida. Los llamantes deberían escoger leer la propiedad "content-length" como un valor de 64 bit pasando a través de nsIPropertyBag2, si esta interfaz está disponible al canal.

Constantes

Flags de carga específicos del canal:

Los bit 22 a 31 están reservados para un uso futuro de esta interfaz o una de sus derivadas (ejem. ver nsICachingChannel).

Constante	Valor	Descripción
`LOAD_DOCUMENT_URI`	`16`	Establecer (p.e. a través de docshell) para indicar si el canal corresponde o no a un documento URI.
`LOAD_RETARGETED_DOCUMENT_URI`	`17`	Si el consumidor final de esta carga ha sido cambiado tras conocer su contenido, este flag será establecido:
`LOAD_REPLACE`	`18`	Este flag se establece a para indicar que este canal está reemplazando a otro canal. Esto significa que: 1) se pasó al método asyncOpen la escucha en la que este canal sería notificado, de algún otro canal y 2) la URI de este canal es un mejor identificador del recurso que está siendo accedido que la URI original del canal. Este flag puede ser establecido, por ejemplo, por redirectores o en casos en que un solo canal tiene múltiples partes (y por tanto pueden seguir onStopRequest con otro par onStartRequest/onStopRequest, cada par para una petición distinta).
`LOAD_INITIAL_DOCUMENT_URI`	`19`	Establecer (p.e. a través de docshell) para indicar si el canal corresponde o no a la URI original de la carga (e.g., link click).
`LOAD_TARGETED`	`20`	Establecer (p.e. por el URILoader) para indicar si el consumidor final para esta carga ha sido determinado.
`LOAD_CALL_CONTENT_SNIFFERS`	`21`	Si este flag está establecido, el canal debería llamar al analizador de contenidos según se describe en nsNetCID.h acerca NS_CONTENT_SNIFFER_CATEGORY. Nota: Los canales pueden ignorar este flag. Sin embargo, la implementación de nuevos canales deberían hacer esto sólo por una buena razón.