Escolar Documentos
Profissional Documentos
Cultura Documentos
Televiso digital terrestre Codificao de dados e especificaes de transmisso para radiodifuso digital Parte 2: Ginga-NCL para receptores fixos e mveis Linguagem de aplicao XML para codificao de aplicaes
Digital terrestrial television Data coding and transmission specification for digital broadcasting Part 2: Ginga-NCL for fixed and mobile receivers XML application language for application coding
Palavras-chave: Televiso digital terrestre. Middleware. Ginga. NCL. Receptores fixos e mveis. Perfil Full-seg. Descriptors: Terrestrial digital televison. Middleware. Ginga. NCL. Mobile and fixed receivers. Full-seg profile. ICS 33.160.01 ISBN 978-85-07-00583-4
ABNT 2007 Todos os direitos reservados. A menos que especificado de outro modo, nenhuma parte desta publicao pode ser reproduzida ou utilizada por qualquer meio, eletrnico ou mecnico, incluindo fotocpia e microfilme, sem permisso por escrito pela ABNT. ABNT Av.Treze de Maio, 13 - 28 andar 20031-901 - Rio de Janeiro - RJ Tel.: + 55 21 3974-2300 Fax: + 55 21 2220-1762 abnt@abnt.org.br www.abnt.org.br Impresso no Brasil
ii
Sumrio
Pgina
Prefcio......................................................................................................................................................................vii Introduo ................................................................................................................................................................viii 1 2 3 4 5 5.1 5.2 6 6.1 6.2 6.3 6.3.1 6.3.2 6.3.3 6.3.4 7 7.1 7.1.1 7.1.2 7.1.3 7.2 7.2.1 7.2.2 7.2.3 7.2.4 7.2.5 7.2.6 7.2.7 7.2.8 7.2.9 7.2.10 7.2.11 7.2.12 7.2.13 7.2.14 7.2.15 7.3 7.3.1 7.3.2 7.3.3 7.3.4 7.3.5 8 8.1 8.2 8.2.1 Escopo ............................................................................................................................................................1 Referncias normativas ................................................................................................................................1 Termos e definies ......................................................................................................................................2 Abreviaturas...................................................................................................................................................8 Arquitetura Ginga ..........................................................................................................................................9 Ginga main modules .....................................................................................................................................9 Interao com o ambiente nativo...............................................................................................................10 Interoperabilidade com ambientes declarativos definidos em outros sistemas de televiso digital Objetos XHTML embutidos em apresentaes NCL................................................................................10 NCL como linguagem cola .........................................................................................................................10 Formato de contedo XHTML ....................................................................................................................12 Harmonizao do formato de contedo XHTML ......................................................................................12 Marcaes XML............................................................................................................................................12 Folhas de estilo............................................................................................................................................17 ECMAScript ..................................................................................................................................................22 API DOM .......................................................................................................................................................26 NCL - Linguagem declarativa XML para especificao de apresentaes multimdia interativas .....28 Linguagens modulares e perfis de linguagens ........................................................................................28 Mdulos NCL................................................................................................................................................28 Identificadores para mdulos e perfis de linguagem da NCL 3.0 ..........................................................30 Informaes sobre verses da NCL ..........................................................................................................32 Mdulos NCL................................................................................................................................................32 Observaes gerais.....................................................................................................................................32 rea funcional Structure.............................................................................................................................33 rea funcional Layout .................................................................................................................................33 rea funcional Components.......................................................................................................................36 rea funcional Interfaces............................................................................................................................42 rea funcional Presentation Specification ...............................................................................................45 rea funcional Linking ................................................................................................................................47 rea funcional Connectors.........................................................................................................................48 rea funcional Presentation Control .........................................................................................................55 rea funcional Timing .................................................................................................................................57 rea funcional Reuse ..................................................................................................................................57 rea funcional Navigational Key................................................................................................................59 rea funcional Animation ...........................................................................................................................61 rea funcional Transition Effects ..............................................................................................................61 rea funcional Metainformation.................................................................................................................63 Perfis da linguagem NCL para o SBTVD ...................................................................................................64 Mdulos de perfis ........................................................................................................................................64 Esquema do perfil NCL 3.0 DTV avanado ...............................................................................................65 The schema of the NCL 3.0 CausalConnector profile..............................................................................74 Atributos e elementos do perfil NCL 3.0 DTV bsico ..............................................................................76 Esquema do perfil NCL 3.0 DTV Bsico ....................................................................................................79 Objetos de mdia em apresentaes NCL.................................................................................................88 Implementao modular de Ginga-NCL ....................................................................................................88 Comportamento esperado dos exibidores de mdia................................................................................88 Instruo start para eventos de apresentao.........................................................................................88
iii
iv
Anexo A (normativo) Esquemas dos mdulos NCL 3.0 usados nos perfis TVD Bsico e TVD Avanado ...158 A.1 Mdulo Structure: NCL30Structure.xsd ..................................................................................................158 A.2 Mdulo Layout: NCL30Layout.xsd ..........................................................................................................159 A.3 Mdulo Media: NCL30Media.xsd..............................................................................................................160 A.4 Mdulo Context: NCL30Context.xsd .......................................................................................................161 A.5 Mdulo MediaContentAnchor: NCL30MediaContentAnchor.xsd .........................................................162 A.6 Mdulo CompositeNodeInterface: NC30CompositeNodeInterface.xsd...............................................164 A.7 Mdulo PropertyAnchor: NCL30PropertyAnchor.xsd ...........................................................................165 A.8 Mdulo SwitchInterface: NCL30SwitchInterface.xsd.............................................................................166 A.9 Mdulo Descriptor: NCL30Descriptor.xsd ..............................................................................................167 A.10 Mdulo Linking: NCL30Linking.xsd ........................................................................................................169 A.11 Mdulo ConnectorCommonPart: NCL30ConnectorCommonPart.xsd ................................................170 A.12 Mdulo ConnectorAssessmentExpression: NCL30ConnectorAssessmentExpression.xsd ...........171 A.13 Mdulo ConnectorCausalExpression: NCL30ConnectorCausalExpression.xsd ...............................173 A.14 Mdulo CausalConnector: NCL30CausalConnector.xsd ......................................................................176 A.15 Mdulo ConnectorBase: NCL30ConnectorBase.xsd.............................................................................177 A.16 NCL30CausalConnectorFunctionality.xsd..............................................................................................178 A.17 Mdulo TestRule: NCL30TestRule.xsd....................................................................................................181 A.18 Mdulo TestRuleUse: NCL30TestRuleUse.xsd ......................................................................................183 A.19 Mdulo ContentControl: NCL30ContentControl.xsd .............................................................................184 A.20 Mdulo DescriptorControl: NCL30DescriptorControl.xsd ....................................................................185 A.21 Mdulo Timing: NCL30Timing.xsd ..........................................................................................................186 A.22 Mdulo Import: NCL30Import.xsd............................................................................................................187 A.23 Mdulo EntityReuse: NCL30EntityReuse.xsd ........................................................................................188 A.24 Mdulo ExtendedEntityReuse: NCL30ExtendedEntityReuse.xsd........................................................189 A.25 Mdulo KeyNavigation: NCL30KeyNavigation.xsd................................................................................190 A.26 Mdulo TransitionBase: NCL30TransitionBase.xsd..............................................................................192 A.27 Mdulo Animation: NCL30Animation.xsd...............................................................................................193 A.28 Transition module: NCL30Transition.xsd ...............................................................................................194 A.29 Metainformation module: NCL30Metainformation.xsd ..............................................................................198 Anexo B (informativo) Manual de referncia de Lua 5.1 .....................................................................................199 B.1 Introduo ..................................................................................................................................................199 B.2 A Linguagem ..............................................................................................................................................199 B.2.1 Notao utilizada .......................................................................................................................................199 B.2.2 Convenes lxicas ..................................................................................................................................199 B.2.3 Valores e tipos ...........................................................................................................................................201 B.2.4 Variveis .....................................................................................................................................................202 B.2.5 Comandos ..................................................................................................................................................203 B.2.6 Expresses.................................................................................................................................................206 B.2.7 Regras de visibilidade...............................................................................................................................212
vi
Prefcio
A Associao Brasileira de Normas Tcnicas (ABNT) o Foro Nacional de Normalizao. As Normas Brasileiras, cujo contedo de responsabilidade dos Comits Brasileiros (ABNT/CB), dos Organismos de Normalizao Setorial (ABNT/ONS) e das Comisses de Estudo Especiais (ABNT/CEE), so elaboradas por Comisses de Estudo (CE), formadas por representantes dos setores envolvidos, delas fazendo parte: produtores, consumidores e neutros (universidade, laboratrio e outros). Os Documentos Tcnicos ABNT so elaborados conforme as regras das Diretivas ABNT, Parte 2. A Associao Brasileira de Normas Tcnicas (ABNT) chama ateno para a possibilidade de que alguns dos elementos deste documento podem ser objeto de direito de patente. A ABNT no deve ser considerada responsvel pela identificao de quaisquer direitos de patentes. A ABNT NBR 15606-2 foi elaborada pela Comisso de Estudo Especial de Televiso Digital (ABNT/CEE-00:001.85). O Projeto circulou em Consulta Nacional conforme Edital n 09, de 06.09.2007 a 05.11.2007, com o nmero de Projeto 00:001.85-006/2. Esta Norma baseada nos trabalhos do Frum do Sistema Brasileiro de Televiso Digital Terrestre, conforme estabelecido no Decreto Presidencial n 5.820, de 29.06.2006. A ABNT NBR 15606, sob o ttulo geral Televiso digital terrestre - Codificao de dados e especificaes de transmisso para radiodifuso digital, tem previso de conter as seguintes partes: Parte 1: Codificao de dados; Parte 2: Ginga-NCL para receptores fixos e mveis Linguagem de aplicao XML para codificao de aplicaes; Parte 3: Especificao de transmisso de dados; Parte 4: Ginga-J Ambiente para a execuo de aplicaes procedurais; Parte 5: Ginga-NCL para receptores portteis Linguagem de aplicao XML para codificao de aplicaes. Esta verso corrigida 3 da ABNT NBR 15606-2 incorpora a Errata 1 de 07.04.2008, Errata 2 de 22.08.2008 e a Errata 3 de 16.04.2009.
vii
Introduo
A Associao Brasileira de Normas Tcnicas (ABNT) chama ateno para o fato de que a exigncia de conformidade com este documento ABNT pode envolver o uso de uma patente relativa a NCL, conforme mencionado em 5.1. A ABNT no se posiciona a respeito de evidncias, validade e escopo deste direito de patente. O proprietrio deste direito de patente assegurou ABNT que ele est preparado para negociar licenas sobre termos e condies razoveis e no discriminatrias com os solicitantes. Sobre isto, uma declarao do proprietrio desta patente est registrada com a ABNT. Informaes podem ser obtidas com: Pontifcia Universidade Catlica do Rio de Janeiro, Departamento de Transferncia de Tecnologia Rua Marqus de So Vicente, 225 Gvea, 22451-900 - Rio de Janeiro - RJ - Brasil. A ABNT chama ateno para a possibilidade de que alguns dos elementos deste documento ABNT podem ser objeto de outros direitos de patente alm dos identificados acima. A ABNT no deve ser considerada responsvel pela identificao de quaisquer direitos de patente. Esta Norma padroniza uma linguagem de aplicao XML que permite aos autores escreverem apresentaes multimdia interativas. Este componente da ABNT NBR 15606 parte das especificaes de codificao de dados para o Sistema Brasileiro de Televiso Digital Terrestre (SBTVD) e compreende a especificao da linguagem utilizada pela mquina de apresentao Ginga-NCL do middleware SBTVD, chamado Ginga. Atravs dessa linguagem, denominada NCL (Nested Context Language Linguagem de Contextos Aninhados), um autor pode descrever o comportamento temporal de uma apresentao multimdia, associar hyperlinks (interao do usurio) a objetos de mdia, definir alternativas para apresentao (adaptao) e descrever o leiaute da apresentao em mltiplos dispositivos. Esta Norma primordialmente destinada s entidades que esto especificando terminais e/ou padres baseados no Ginga. Tambm destinada aos desenvolvedores de aplicaes que utilizam as funcionalidades do Ginga e de suas API. O middleware Ginga tem como objetivo garantir a interoperabilidade das aplicaes em diferentes implementaes de plataformas que o suportam. As aplicaes Ginga so classificadas sob duas categorias, dependendo se a aplicao inicialmente processada possui contedo de natureza declarativa ou imperativa. Essas categorias de aplicaes so chamadas de aplicaes declarativas e aplicaes procedurais, respectivamente. Os ambientes de aplicao so igualmente classificados em duas categorias, dependendo se eles processam aplicaes declarativas ou procedurais, sendo ento chamados de Ginga-NCL e Ginga-J, respectivamente. importante observar que a uma implementao unicamente Ginga-NCL ou unicamente Ginga-J, seja em receptores fixos ou mveis, proibida a reivindicao de qualquer tipo de conformidade com o SBTVD. Isso garante que o Ginga oferea perfis sempre compatveis com verses anteriores. Esta Norma no especifica a forma como os ambientes de aplicao devem ser implementados em um receptor em conformidade. Um fabricante de receptores pode implementar os dois ambientes como um nico subsistema; alternativamente, os ambientes podem ser implementados como subsistemas distintos, com interfaces internas bem definidas entre os ambientes.
viii
NORMA BRASILEIRA
Televiso digital terrestre Codificao de dados e especificaes de transmisso para radiodifuso digital Parte 2: Ginga-NCL para receptores fixos e mveis Linguagem de aplicao XML para codificao de aplicaes
Escopo
Esta parte da ABNT NBR 15606 especifica uma linguagem de aplicao XML denominada NCL (Nested Context Language), a linguagem declarativa do middleware Ginga, a codificao e a transmisso de dados para radiodifuso digital.
Referncias normativas
Os documentos relacionados a seguir so indispensveis aplicao deste documento. Para referncias datadas, aplicam-se somente as edies citadas. Para referncias no datadas, aplicam-se as edies mais recentes do referido documento (incluindo emendas). ABNT NBR 15601, Televiso digital terrestre Padro de transmisso ABNT NBR 15603-2:2007, Televiso digital terrestre Multiplexao e servios de informao (SI) Parte 2: Estrutura de dados e definies da informao bsica de SI ABNT NBR 15606-1, Televiso digital terrestre Codificao de dados e especificaes de transmisso para radiodifuso digital Parte 1: Codificao de dados ABNT NBR 15606-3, Televiso digital terrestre Codificao de dados e especificaes de transmisso para radiodifuso digital Parte 3: Especificao de transmisso de dados ISO 639-1, Codes for the representation of names of languages Part 1: Alpha-2 code ISO 8859-1, Information technology 8-bit single-byte coded graphic character sets - Part 1: Latin alphabet N 1 ISO/IEC 11172-1, Coding of moving pictures and associated audio for digital storage mediaat up to about 1,5 Mbit/s Part 1 Systems ISO/IEC 11172-2, Coding of moving pictures and associated audio for digital storage mediaat up to about 1,5 Mbit/s Part 2 Video ISO/IEC 11172-3, Coding of moving pictures and associated audio for digital storage mediaat up to about 1,5 Mbit/s Part 3 Audio ISO/IEC 13818-1, Information technology Generic coding of moving pictures and associated audio information Part 1:Systems ISO/IEC 13818-2, Information technology Generic coding of moving pictures and associated audio information Part 2:Video ISO/IEC 13818-3, Information technology Generic coding of moving pictures and associated audio information Part 3: Audio ISO/IEC 13818-6, Information technology Generic coding of moving pictures and associated audio information Part 6: Extensions for DSM-CC
ISO/IEC 13818-7, Information technology Generic coding of moving pictures and associated audio information Part 7: Advanced Audio Coding (AAC) ISO/IEC 14496-3, Information technology Coding of audio-visual objects Part 3: Audio ECMA 262, ECMAScript language specification
Termos e definies
Para os efeitos desta parte da ABNT NBR 15606, aplicam-se os seguintes termos e definies. 3.1 ambiente de aplicao contexto ou ambiente de software no qual uma aplicao processada 3.2 ambiente de aplicao declarativa ambiente que suporta o processamento de aplicaes declarativas
NOTA Um formatador (user agent) NCL um exemplo de ambiente de aplicao declarativa.
3.3 ambiente de aplicao procedural ambiente que suporta o processamento de aplicaes procedurais 3.4 API DOM API que define a estrutura lgica de um documento XML e a forma de acessar, ou manipular, um documento XML
NOTA Model). Esta API uma interface independente de plataformas e linguagens e segue o Modelo DOM (Document Object
3.5 aplicao informao que expressa um conjunto especfico de comportamentos observveis 3.6 aplicao declarativa aplicao que utiliza principalmente, e como ponto de partida, informao declarativa para expressar seu comportamento
NOTA Uma instncia de documento NCL um exemplo de aplicao declarativa.
3.7 aplicao hbrida aplicao hbrida declarativa ou aplicao hbrida procedural 3.8 aplicao hbrida declarativa aplicao declarativa que contm contedo de objeto ativo
NOTA Um documento NCL com um Java Xlet embutido um exemplo de aplicao hbrida declarativa.
3.10 aplicao nativa funo intrnseca implementada por uma plataforma receptora
NOTA Uma exibio em closed caption um exemplo de aplicao nativa.
3.11 aplicao procedural aplicao que utiliza principalmente, e como ponto de partida, informaes procedurais para expressar o seu comportamento
NOTA Um programa em Java um exemplo de uma aplicao procedural.
3.12 armazenamento persistente memria disponvel que pode ser lida ou escrita por uma aplicao e pode ser mantida por mais tempo do que o tempo de vida da prpria aplicao
NOTA O armazenamento persistente pode ser voltil ou no-voltil.
3.13 atributo parmetro para representar a natureza de uma propriedade 3.14 atributo de um elemento propriedade de um elemento XML 3.15 autor pessoa que escreve documentos NCL 3.16 canal de interatividade canal de retorno mecanismo de comunicao que fornece conexo entre o receptor e um servidor remoto 3.17 caractere "letra" especfica ou outro smbolo identificvel
EXEMPLO A
3.18 carrossel de dados mtodo que envia qualquer conjunto de dados ciclicamente, para que esses dados possam ser obtidos, via radiodifuso, em um intervalo de tempo to longo quanto necessrio [ISO/IEC 13818-6:2001] 3.19 codificao de caracteres mapeamento entre um valor de entrada inteiro e o caractere textual, representado por esse mapeamento 3.20 contedo de objeto ativo tipo de contedo que toma a forma de um programa executvel
NOTA Um Xlet Java compilado um exemplo de contedo de objeto ativo.
3.21 contedo NCL conjunto de informaes que consiste em um documento NCL e em um grupo de dados, incluindo objetos (de mdia ou de execuo), que acompanham o documento NCL 3.22 digital storage media command and control DSM-CC mtodo de controle que fornece acesso a um arquivo ou fluxo em servios digitais interativos [ISO/IEC 13818-6:2001] 3.23 document type definition DTD declarao que descreve um tipo de documento XML 3.24 ECMAScript linguagem de programao definida na ECMA 262 3.25 elemento unidade de estruturao do documento delimitada por tags
NOTA Um elemento usualmente delimitado por uma tag inicial e uma tag final, exceto um elemento vazio que delimitado por uma tag de elemento vazio.
3.26 elemento property elemento NCL que define um nome de propriedade e seu valor associado 3.27 entidade da aplicao unidade de informao que expressa alguma parte de uma aplicao 3.28 evento ocorrncia no tempo que pode ser instantnea ou ter durao mensurvel 3.29 exibidor de mdia media player componente identificvel de um ambiente de aplicao que decodifica ou executa um tipo especfico de contedo 3.30 eXtensible HTML XHTML verso estendida do HTML como aplicao XML
NOTA Na especificao XHTML, um documento HTML reconhecido como aplicao XML.
3.31 ferramenta de autoria ferramenta para auxiliar os autores a criar documentos NCL
3.33 formatador NCL componente de software responsvel por receber a especificao de um documento NCL e controlar sua apresentao, tentando garantir que os relacionamentos entre os objetos de mdia, especificados pelo autor, sejam respeitados
NOTA Renderizador (renderer) de documentos, agente do usurio (user agent) e exibidor so outros nomes usados com o mesmo significado do formatador de documentos.
3.34 fluxo de transporte refere-se sintaxe do fluxo de transporte MPEG-2 para empacotamento e multiplexao de vdeo, udio e sinais de dados em sistemas de radiodifuso digital 3.35 fluxo elementar elementary stream ES fluxo bsico que contm dados de vdeo, udio, ou dados privados
NOTA Um nico fluxo elementar transportado em uma seqncia de pacotes PES com um e apenas um identificador (stream_id).
3.36 gerenciador de aplicaes entidade responsvel por administrar o ciclo de vida das aplicaes e que gerencia as aplicaes, rodando tanto na mquina de apresentao quanto na mquina de execuo 3.37 identificador de pacote PID valor inteiro nico utilizado para associar os fluxos elementares de um programa, tanto em um fluxo de transporte nico como em multiprograma 3.38 informao de servio SI dados que descrevem programas e servios 3.39 informaes especficas do programa program specific information PSI dados normativos necessrios para demultiplexar os fluxos de transporte e regenerar os programas 3.40 interface de programao da aplicao API bibliotecas de software que oferecem acesso uniforme aos servios do sistema
3.41 linguagem de marcao formalismo que descreve uma classe de documentos que empregam marcao para delinear a estrutura, aparncia ou outros aspectos do documento 3.42 linguagem de script linguagem utilizada para descrever um contedo de objeto ativo embutido em documentos NCL e em documentos HTML 3.43 localizador identificador que fornece uma referncia a uma aplicao ou recurso 3.44 mquina de apresentao subsistema em um receptor que analisa e apresenta aplicaes declarativas, com contedos como udio, vdeo, grficos e texto, baseadas em regras definidas na mquina de apresentao
NOTA Uma mquina de apresentao responsvel pelo controle do comportamento da apresentao e por iniciar outros processos em resposta a entradas do usurio e outros eventos. EXEMPLO Navegador HTML e formatador NCL.
3.45 mquina de execuo subsistema em um receptor que avalia e executa aplicaes procedurais, consistindo em instrues em linguagem de computador, contedo de mdia associados e outros dados
NOTA Uma mquina de execuo pode ser implementada com um sistema operacional, compiladores de linguagem de computador, interpretadores e interfaces de programao de aplicaes (API), que uma aplicao procedural pode utilizar para apresentar contedo audiovisual, interagir com o usurio ou executar outras tarefas que no sejam evidentes ao usurio. EXEMPLO Ambiente de software JavaTV, utilizando linguagem de programao Java e interpretador bytecode, API JavaTV e mquina virtual Java para execuo do programa.
3.46 mtodo funo associada a um objeto que tem permisso de manipular os dados do objeto 3.47 n NCL elemento <media>, <context>, <body> ou <switch> de NCL 3.48 normal play time NPT coordenada temporal absoluta que representa a posio em um fluxo 3.49 objeto de mdia coleo de pedaos de dados identificados por nome que pode representar um contedo de mdia ou um programa escrito em linguagem especfica 3.50 perfil especificao de uma classe de capacidades, oferecendo diferentes nveis de funcionalidades em um receptor
3.51 perfil one-seg caracteriza o servio que pode ser recebido por um sintonizador de banda estreita (430 KHz) e portanto com economia no consumo de bateria
NOTA O perfil one-seg tambm conhecido como perfil porttil.
3.52 perfil full-seg caracteriza o servio que precisa necessariamente de um demodulador de faixa larga (5,7 MHz) para ser recebido
NOTA Dependendo das configuraes de transmisso e de funcionalidade especficas do receptor, pode ser recebido em movimento ou apenas por receptores fixos, porm sem o benefcio da economia de energia. A resoluo do vdeo transmitido pode ser ou no de alta definio.
3.53 plug-in conjunto de funcionalidades que pode ser adicionado a uma plataforma genrica para fornecer funcionalidade adicional 3.54 plataforma receptora plataforma hardware, sistema operacional e bibliotecas de software nativas do receptor, escolhidos pelo fabricante 3.55 recurso objeto de dados ou um servio da rede que identificado univocamente 3.56 sistema de arquivos local sistema de arquivos fornecido pela plataforma receptora local 3.57 tempo de vida de uma aplicao perodo de tempo entre o momento em que uma aplicao carregada e o momento em que ela destruda 3.58 uniform resource identifier URI mtodo de endereamento que permite o acesso a objetos em uma rede 3.59 user agent qualquer programa que interpreta um documento NCL
NOTA Um user agent pode exibir um documento, tentando garantir que as relaes especificadas pelo autor entre objetos de mdia sejam respeitadas, pronunci-lo em udio sintetizado, convert-lo para um outro formato etc.
3.60 usurio pessoa que interage com um formatador para visualizar, ouvir ou utilizar de outra forma um documento NCL 3.61 usurio final indivduo que opera ou interage com um receptor
Abreviaturas
Para os efeitos desta parte da ABNT NBR 15606, aplicam-se as seguintes abreviaturas. API BML CLUT CSS DOM DSM-CC DTD DTV DVB GIF HTML HTTP JPEG MIME MNG MPEG NCL NCM NPT OS PAT PES PID PMT PNG PSI SBTVD SMIL TS UCS URI URL XHTML XML W3C Application Programming Interface Broadcast Markup Language Color Look-up Table Cascading Style Sheets Document Object Model Digital Storage Media Command and Control Document Type Definition Digital Television Digital Video Broadcasting Graphics Interchange Format Hypertext Markup Language Hypertext Transfer Protocol Joint Photographic Expert Group Multipurpose Internet Mail Extensions Multiple Network Graphics Moving Picture Expert Group Nested Context Language Nested Context Model Normal Play Time Operating System Program Association Table Packetized Elementary Stream Packet Identifier Program Map Table Portable Network Graphics Program Specific Information Sistema Brasileiro de Televiso Digital Terrestre Synchronized Multimedia Integration Language Transport Stream Universal (Coded) Character Set Universal Resource Identifier Universal Resource Locator eXtensible HTML Extensible Markup Language World-Wide Web Consortium
5
5.1
Arquitetura Ginga
Ginga main modules
O universo das aplicaes Ginga pode ser particionado em um conjunto de aplicaes declarativas e um conjunto de aplicaes procedurais. Uma aplicao declarativa aquela onde o tipo do contedo da entidade inicial declarativo. Por outro lado, uma aplicao procedural aquela cujo tipo do contedo da entidade inicial procedural. Uma aplicao declarativa pura aquela na qual o contedo de todas as entidades do tipo declarativo. Uma aplicao procedural pura aquela na qual o contedo de todas as entidades do tipo procedural. Uma aplicao hbrida aquela cujo conjunto de entidades possui tanto contedo do tipo declarativo quanto procedural. Uma aplicao Ginga no necessita ser puramente declarativa ou procedural. Em particular, as aplicaes declarativas freqentemente fazem uso de scripts, cujo contedo de natureza procedural. Alm disso, uma aplicao declarativa pode fazer referncia a um cdigo Java TV Xlet embutido. Da mesma forma, uma aplicao procedural pode fazer referncia a uma aplicao declarativa, contendo, por exemplo, contedo grfico, ou pode construir e iniciar a apresentao de aplicaes com contedo declarativo. Portanto, ambos os tipos de aplicao Ginga podem utilizar as facilidades dos ambientes de aplicao declarativo e procedural. Ginga-NCL um subsistema lgico do sistema Ginga responsvel pelo processamento de documentos NCL1). Um componente-chave do Ginga-NCL a mquina de interpretao do contedo declarativo (formatador NCL). Outros mdulos importantes so o exibidor (user agent) XHTML, que inclui interpretadores CSS e ECMAScript, e a mquina de apresentao Lua, que responsvel pela interpretao dos scripts Lua (ver Anexo B). Ginga-J um subsistema lgico do sistema Ginga responsvel pelo processamento de contedos ativos. Um componente-chave do ambiente de aplicao procedural a mquina de execuo do contedo procedural, composta por uma mquina virtual Java. Decodificadores de contedo comuns servem tanto s aplicaes procedurais quanto s declarativas que necessitam decodificar e apresentar tipos comuns de contedo como PNG, JPEG, MPEG e outros formatos. O ncleo comum ginga (Ginga Common Core) composto pelos decodificadores de contedo comuns e por procedimentos para obter contedos transportados em fluxos de transporte (transport streams) MPEG-2 e atravs do canal de interatividade. O ncleo comum ginga tambm deve obrigatoriamente suportar o modelo conceitual de exibio, conforme descrito na ABNT NBR 15606-1. A arquitetura (ver Figura 1) e facilidades Ginga foram projetadas para serem aplicadas a sistemas de radiodifuso e receptores terrestres de radiodifuso. Adicionalmente, a mesma arquitetura e facilidades podem ser aplicadas a sistemas que utilizam outros mecanismos de transporte de dados (como sistemas de televiso via satlite ou a cabo).
Sistema operacional Ginga ncleo comum JVM Ginga - servios especficos API
LUA-NCL
API de exibidores
API XHTML
API NCL
Ponte
Mquina de apresentao (JPEG, MPEG2, MPEG4, MP3, TXT, (Formatador NCL) GIF, HTML-based,
etc)
Exibidores de Mdias
Mquina de execuo
Filtro de Sees (Gerenciador Xlet) Sintonizador
NCL marca registrada e sua especificao propriedade intelectual da PUC-Rio (INPI Departamento de Transferncia Tecnolgica - No. 0007162-5; 20/12/2005).
1)
5.2
Em geral, o Ginga alheio a quaisquer aplicaes nativas que podem tambm optar por utilizar o plano grfico. Isso inclui, mas no se limita a aplicaes como: closed caption, mensagens do sistema de acesso condicional (CA), menus do receptor e guias de programao nativos. As aplicaes nativas podem ter prioridade sobre as aplicaes Ginga. O closed caption e as mensagens de emergncia devem obrigatoriamente ter prioridade sobre o sistema Ginga. Algumas aplicaes nativas, como o closed caption, representam um caso especial no qual a aplicao nativa pode estar ativa por longos perodos juntamente com as aplicaes Ginga.
6 Interoperabilidade com ambientes declarativos definidos em outros sistemas de televiso digital - Objetos XHTML embutidos em apresentaes NCL
6.1 NCL como linguagem cola
Todas as mquinas de apresentao dos trs principais sistemas de televiso digital utilizam uma linguagem baseada em XHTML. XHTML uma linguagem declarativa baseada em mdias, o que significa que a sua estrutura definida pelos relacionamentos entre objetos XHTML (documentos XHTML ou objetos inseridos em documentos XHTML) que esto embutidos no contedo das mdias do documento. XHTML pode ento ser classificada como linguagem de marcao: um formalismo que descreve uma classe de documentos que empregam marcao para delinear a estrutura, aparncia e outros aspectos dos documentos. Os relacionamentos de referncia definidos pelos links XHTML so o foco dessa linguagem declarativa. Outros tipos de relacionamentos, como relacionamentos de sincronizao espao-temporal e relacionamentos alternativos (adaptao da mdia), so usualmente definidos atravs de uma linguagem imperativa (por exemplo, ECMAScript). Diferentemente de XHTML ou HTML, NCL define uma separao bem demarcada entre o contedo e a estrutura de um documento (ou aplicativo), provendo um controle no invasivo da ligao entre o contedo e sua apresentao e leiaute. O foco da linguagem declarativa NCL mais amplo do que o oferecido pela XHTML. A sincronizao espaotemporal, definida genericamente pelos links NCL; adaptabilidade, definida pelos elementos switch e descriptor switch da NCL; e suporte a mltiplos dispositivos de exibio, definidos por regies NCL, o foco dessa linguagem declarativa. A interao do usurio tratada apenas como caso particular de sincronizao temporal. Como a NCL tem uma separao mais acurada entre o contedo e a estrutura, ela no define nenhuma mdia em si. Ao contrrio, ela define a cola que prende as mdias em apresentaes multimdia. Um documento NCL apenas define como os objetos de mdia so estruturados e relacionados no tempo e espao. Como uma linguagem de cola, ela no restringe ou prescreve os tipos de contedo dos objetos de mdia. Nesse sentido, pode-se ter objetos de imagem (GIF, JPEG etc.), de vdeo (MPEG, MOV etc.), de udio (MP3, WMA etc.), de texto (TXT, PDF etc.), de execuo (Xlet, Lua etc.), entre outros, como objetos de mdia NCL. Quais objetos de mdia so suportados depende dos exibidores de mdia que esto acoplados ao formatador NCL (exibidor NCL). Um desses exibidores o decodificador/exibidor MPEG-4, normalmente implementado em hardware no receptor de televiso digital. Dessa forma, o vdeo e o udio MPEG-4 principal so tratados como todos os demais objetos de mdia que podem estar relacionados utilizando NCL. Outro objeto de mdia NCL que deve obrigatoriamente ser suportado o objeto de mdia baseado em XHTML. A NCL no substitui, mas embute documentos (ou objetos) baseados em XHTML. Como acontece com outros objetos de mdia, qual linguagem baseada em XHTML tem suporte em um formatador NCL uma escolha de implementao e, portanto, depende de qual navegador XHTML, incorporado no formatador NCL, atua como exibidor dessa mdia.
10
Como conseqncia, possvel ter navegadores BML, DVB-HTML e ACAP-X individualmente embutidos em um exibidor de documento NCL. possvel, ainda, ter todos eles. igualmente possvel receber o cdigo de um programa navegador atravs da difuso de dados e instal-lo como plug-in (normalmente um plug-in Java). Tambm possvel ter um navegador genrico implementado e, se necessrio, receber a parte complementar (especfica) como um plug-in, para converter o exibidor XHTML genrico em um exibidor especfico de um dos diversos padres de navegador DTV. Em ltimo caso, um documento NCL pode ser reduzido para conter apenas um objeto de mdia XHTML. Nesse caso, o exibidor do documento NCL atua quase como um navegador XHTML, isto , como qualquer outro navegador dos padres supracitados. No importa o caso, a implementao do navegador XHTML deve ser uma conseqncia das seguintes exigncias: interoperabilidade; robustez; conformidade com as normas do W3C; rejeio de contedo no conforme; compatibilidade com o modelo de segurana Ginga; minimizao da redundncia com a tecnologia Ginga-J existente; minimizao da redundncia com as facilidades NCL existentes; mecanismos precisos de controle do leiaute do contedo; suporte a diferentes razes de aspecto das unidades de exibio (pixels). Para suportar as facilidades do navegador XHTML definidas por outros padres DTV, recomenda-se que todas as especificaes SBTVD relacionadas difuso de dados suportem tambm as facilidades definidas para tais navegadores, como o transporte de eventos de fluxos (stream events), por exemplo. Embora um navegador XHTML deva obrigatoriamente ser suportado, recomenda-se que a utilizao de elementos XHTML para definir relacionamentos (inclusive links XHTML) seja evitada na autoria de documentos NCL. Recomenda-se que a autoria baseada na estrutura seja priorizada por razes conhecidas e amplamente divulgadas na literatura. Durante a exibio do contedo de objetos de mdia so gerados vrios eventos (ver 7.2.8). Alguns exemplos so a apresentao de parte do contedo de um objeto de mdia, a seleo de parte do contedo de um objeto etc. Os eventos podem gerar aes sobre outros objetos de mdia, como iniciar ou terminar suas apresentaes. Portanto, os eventos devem obrigatoriamente ser relatados pelos exibidores de mdia ao formatador NCL que, por sua vez, pode gerar aes a serem aplicadas a esses ou outros exibidores. Ginga-NCL define a API (ver Seo 8) de um adaptador com o objetivo de padronizar a interface entre o formatador Ginga-NCL e cada exibidor especfico. Para que qualquer exibidor de mdia, em particular um navegador XHTML, seja acoplado ao formatador Ginga-NCL, ele deve obrigatoriamente suportar a API dos adaptadores. Assim, para alguns exibidores de mdia, inclusive navegadores XHTML, um mdulo adaptador pode ser necessrio para que a integrao seja alcanada.
11
Para edio ao vivo, o Ginga-NCL tambm define eventos de fluxo NCL para oferecer suporte aos eventos gerados ao vivo sobre fluxos de mdia, em particular sobre o fluxo de vdeo do programa principal. Esses eventos so uma generalizao do mesmo conceito encontrado em outras normas, como, por exemplo, os bevents de BML. Embora um navegador XHTML deva obrigatoriamente ser suportado, recomenda-se que a utilizao de elementos XHTML para definir relacionamentos (inclusive eventos de fluxo) seja evitada quando da criao de documentos NCL, pela mesma razo, isto , recomenda-se que a autoria baseada na estrutura seja priorizada por razes conhecidas e amplamente divulgadas na literatura.
6.2
Formatos comuns de contedo devem obrigatoriamente ser adotados para a produo e intercmbio de contedo multimdia, como definido na ABNT NBR 15606-1. Alm disso, no ambiente de aplicao declarativa tambm exigida a especificao de formatos comuns de contedos XHTML para as aplicaes de televiso interativa.
NOTA Esta Norma segue a ITU Recommendation J.201 para identificar as funcionalidades comuns entre os ambientes de aplicao declarativa para aplicaes de televiso interativa especificadas por DVB-HTML, ACAP-X e BML.
Convm que os elementos comuns e API no nvel sinttico de objetos de mdia XHTML embutidos em aplicaes NCL sejam especificados, para auxiliar os autores na criao de contedo XHTML. Qualquer implementao de objeto de mdia XHTML de acordo com esta Norma deve obrigatoriamente dar suporte a pelo menos todas as marcaes XML e propriedades de folhas de estilo em comum aos servios bsicos BML ("perfil terminal fixo"), ACAP-X e DVB-HTML, como definido em 6.3. recomendado que facilidades de objetos nativos ECMAScript e API DOM, em comum aos servios bsicos BML ("perfil terminal fixo"), ACAP-X e DVB-HTML, tambm tenham suporte.
6.3
6.3.1
NOTA Objetos de mdia NCL baseados em XHTML seguem a recomendao W3C Modularization of XHTML e suas marcaes XML so definidas na ITU Recommendation J.201.
Os mdulos em comum de marcaes XML podem ser: structure; text; hypertext; list; presentation; bidirectional text; forms; image; client-side image map; object; frames;
12
target; meta information; scripting; stylesheet; style attribute; link; base. As colees de atributo XHTML so definidas de acordo com a Tabela 1. As marcaes XML em comum dos padres servios bsicos BML (perfil de terminal fixo), ACAP-X e DVB-HTML, que devem obrigatoriamente ser suportadas por qualquer implementao, so listadas na Tabela 2, em conjunto com as extenses Ginga obrigatrias. Tabela 1 Colees de atributos Nome da coleo Core I18N Atributos na coleo class (NMTOKENS) Id (ID), title (CDATA) xml:lang (CDATA) onclick (Script) ondblclick (Script) onmousedown (Script) onmouseup (Script) Events onmouseover (Script) onmousemove (Script) onmouseout (Script) onkeypress (Script) onkeydown (Script) onkeyup (Script) Style Common style (CDATA) Core + Events + I18N + Style Condio do atributo Requerido Requerido Requerido Requerido Requerido Requerido Requerido
13
Tabela 2 Elementos de marcao XML em comum Mdulo Elemento body Structure head html title abbr acronym address blockquote br cite code dfn div em h1 h2 h3 h4 h5 h6 kbd p pre q samp span strong var Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Condio do elemento Requerido Atributo %Common.attrib %Core.attrib %I18n.attrib %Events.attrib %I18n.attrib profile %I18n.attrib Condio do atributo Requerido Requerido Requerido Requerido
%Core.attrib
Requerido
Text
Core
%Common.attrib %Common.attrib accesskey charset href hreflang rel rev tabindex type
Hypertext
Requerido
List
dl dt dd ol ul li
14
Tabela 2 (continuao) Mdulo Applet Elemento applet param b big hr i small sub sup tt del ins bdo form input label select option textarea Condio do elemento %Common.attrib action method enctype accept-charset accept name %Common.attrib accesskey checked disabled readonly maxlength alt name size src tabindex accept type value Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Atributo Condio do atributo
Basic forms
form
Requerido
15
Tabela 2 (continuao) Mdulo Elemento caption table td th tr caption table td th tr col colgroup tbody thead tfoot img a& area img& input& map object& img& Input& Condio do elemento Atributo Condio do atributo
Basic tables
Table Tables
Object
object
Requerido
%Common.attrib archive classid codebase codetype data declare height name standby tabindex type width
Frames
Target
IFrame
param frameset frame noframe a& area& base& link& form& iframe
16
Tabela 2 (continuao) Mdulo Elemento a& area& frameset& form& body& label& input& select& textarea& button& Condio do elemento Requerido Atributo Condio do atributo
Intrinsic events
Metainformation
meta
Requerido
%I18n.attrib http-equiv name content scheme charset type src defer %I18n.attrib id type media title
Stylesheet
style
Requerido
link base
Requerido Requerido
17
Tabela 3 Propriedades de folhas de estilo em comum background background-attachment background-color background-image background-position background-repeat border border-bottom border-bottom-color border-bottom-style border-bottom-width border-color border-left border-left-color border-left-style border-left-width border-right border-right-color border-right-style border-right-width border-style border-top border-top-color border-top-style border-top-width border-width bottom caption-side clear clip color content counter-increment counter-reset display float font font-family font-size font-style font-variant font-weight height left letter-spacing line-height list-style list-style-image list-style-position list-style-type margin margin-bottom margin-left margin-right margin-top outline outline-color outline-style outline-width overflow padding padding-bottom padding-left padding-right padding-top position right text-align text-decoration text-indent text-transform top vertical-align visibility white-space width word-spacing z-index nav-down nav-index nav-left nav-right nav-up ----
As propriedades de folhas de estilo em comum aos padres servios bsicos BML, ACAP-X e DVB-HTML, que devem obrigatoriamente ser suportadas por qualquer implementao, so listadas na Tabela 4.
18
19
Tabela 4 (continuao)
Propriedade Condio da propriedade unicode-bidi min-width max-width min-height max-height Other visual effects visibility Requerido overflow Requerido clip Generated content/Auto numbering/List content quotes counter-reset counter-increment marker-offset list-style-type list-style-image list-style-position list-style Page media "@page" size marks page-break-before page-break-after page-break-inside page orphans widows Background background background-color background-image Requerido background-repeat Requerido background-position background-attachment Font color Requerido font-family Requerido font-style Requerido font-size Requerido font-variant Requerido font-weight Requerido font Requerido font-stretch font-adjust Text text-indent text-align Requerido
text-decoration
20
Tabela 4 (continuao)
Propriedade text-shadow letter-spacing word-spacing text-transform white-space Pseudo class/ Pseudo element :link :visited :active :hover :focus :lang :first-child :first-line :first-letter :before :after Table caption-side border-collapse border-spacing table-layout empty-cells speak-header User interface outline-color outline-width outline-style outline cursor Voice style sheet volume speak pause-before pause-after pause cue-before cue-after cue play-during azimuth elevation speech-rate voice-family pitch pitch-range stress richness speak-punctuation peak-numeral Condio da propriedade Requerido Requerido Requerido Requerido
21
Tabela 4 (continuao)
Propriedade Extended property clut color-index background-color-index border-color-index border-top-color-index border-right-color-index border-bottom-color-index border-left-color-index outline-color-index resolution display-aspect-ratio grayscale-color-index nav-index nav-up nav-down nav-left nav-right used-key-list Condio da propriedade
As seguintes restries devem obrigatoriamente ser aplicadas s propriedades de exibio: somente elementos de bloco podem ser aplicados para <p>, <div>, <body>, <input> e <object>; somente valores definidos no prprio elemento HTML podem ser aplicados para <br>, <a> e <span>. Alm disso, as seguintes restries devem obrigatoriamente ser aplicadas s propriedades de posio: somente valores absolutos podem ser aplicados para <p>, <div>, <input> e <object>; somente valores estticos podem ser aplicados para <br>, <span> e <a>. Os seletores CSS em comum dos padres servios bsicos BML, ACAP-X e DVB-HTML, que devem obrigatoriamente ser suportados por qualquer implementao, so os seguintes: universal; type; class; id; dynamic (:active and :focus). 6.3.3 ECMAScript
Quando implementada, fortemente recomendado que a mquina ECMAScript d suporte aos objetos nativos em comum dos padres de servios bsicos BML, ACAP-X e DVB-HTML, listados na Tabela 5. Como restrio, os tipos numricos suportam apenas operaes inteiras.
22
Tabela 5 Objetos nativos em comum Object (global) Method, properties NaN Infinity eval(x) parseInt(string, radix) parseFloat(string) escape(string) unescape(string) isNaN(number) O isFinite(number) Object prototype Object([value]) new Object([value]) Object.prototype constructor toString() valueOf() Function prototype Length Function(p1, p2, . . . , pn, body) new Function(p1, p2, . . . , pn, body) Function.prototype constructor toString() Array prototype Length Array(item0, item1, . . .) new Array(item0, item1, . . .) new Array([len]) Array.prototype constructor toString() join([separator]) reverse() sort([comparefn]) constructor String prototype Length String([value]) new String([value]) String.fromCharCode(char0[, char1, . . .]) Requerido Requerido Todos requeridos Requerido Requerido Todos requeridos Requerido Requerido Requerido Requerido Requerido Todos requeridos Requerido Requerido Requerido Requerido Requerido Requerido Todos requeridos Requerido Requerido Requerido Requerido Requerido Operation condition Requerido Requerido Requerido Todos requeridos Requerido Requerido Requerido Todos requeridos Requerido Requerido Requerido
23
Tabela 5 (continuao) Object String.prototype Method, properties constructor toString() valueOf() charAt(pos) charCodeAt(pos) indexOf(searchString, position) lastIndexOf(searchString, position) split(separator) substring(start [,end]) toLowerCase() toUpperCase() Boolean prototype Boolean([value]) new Boolean([value]) Boolean.prototype constructor toString() valueOf() Number prototype MAX_VALUE MIN_VALUE NaN NEGATIVE_INFINITY POSITIVE_INFINITY Number([value]) new Number([value]) Number.prototype constructor toString([radix]) valueOf() Math E LN10 LN2 LOG2E LOG10E PI SQRT1_2 SQRT2 abs(x) acos(x) asin(x) atan(x) atan2(y, x) cos(x) Requerido Requerido Requerido Requerido Requerido Requerido Todos requeridos Requerido Requerido Requerido Operation condition Todos requeridos Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Todos requeridos Requerido Requerido Requerido Todos requeridos Requerido Requerido Requerido
24
Tabela 5 (continuao) Object Math exp(x) floor(x) log(x) max(x, y) min(x, y) pow(x, y) random() round(x) sin(x) sqrt(x) tan(x) Date prototype Date([year, month [, date [, hours [, minutes [,seconds [, ms ] ] ] ] ] ]) new Date([year, month [, date [, hours [, minutes[, seconds [, ms ] ] ] ] ] ]) Date(value) new Date(value) Date.parse(string) Date.UTC([year [, month [, date [, hours [,minutes [, seconds [, ms] ] ] ] ] ] ]) Date.prototype constructor toString() valueOf() getTime() getYear()) getFullYear() getUTCFullYear() getMonth() getUTCMonth() getDate() getUTCDate() getDay() getUTCDay() getHours() getUTCHours() getMinutes() getUTCMinutes() getSeconds() getUTCSeconds() getMilliseconds() getUTCMilliseconds() getTimezoneOffset() setTime(time) setMilliseconds(ms) setUTCMilliseconds(ms) Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Method, properties Operation condition
25
Tabela 5 (continuao) Object Date.prototype Method, properties setSeconds(sec [, ms ] ) setUTCSeconds(sec [, ms ] ) setMinutes(min [, sec [, ms ] ] ) setUTCMinutes(min [, sec [, ms ] ] ) setHours(hour [, min [, sec [, ms ] ] ] ) setUTCHours(hour [, min [, sec [, ms ] ] ] ) setDate(date) setMonth(mon [, date ] ) setUTCMonth(mon [, date ]) setFullYear(year [, mon [, date ] ] ) setUTCFullYear(year [, mon [, date ] ] ) setYear(year) toLocaleString() toUTCString() toGMTString() Operation condition Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido Requerido
Dependendo da implementao do middleware, possvel ter funes ECMAScript mapeadas para as API fornecidas pelo Ginga-J, obtendo acesso a alguns recursos da plataforma receptora e facilidades Ginga. Nesse caso, recomenda-se que a API fornecida no ECMAScript siga a mesma especificao apresentada para o ambiente procedural do Ginga-J. 6.3.4 API DOM
As API DOM nvel 1 so as seguintes: DOMException; DOMImplementation; DocumentFragment; Document; Node; NodeList; NamedNodeMap; CharacterData; Attr; Element; Text; Comment. recomendado que as API DOM Nvel 1, quando implementadas, sigam as API comuns do DOM nvel 1 para servios bsicos BML, ACAP-X e DVB-HTML, listadas na Tabela 6.
26
27
A abordagem modular tem sido utilizada em vrias linguagens recomendadas pelo W3C. Mdulos so colees de elementos, atributos e valores de atributos XML semanticamente relacionados que representam uma unidade de funcionalidade. Mdulos so definidos em conjuntos coerentes. Essa coerncia expressa por meio da associao de um mesmo namespace aos elementos desses mdulos.
NOTA Namespaces so discutidos em Namespaces in XML:1999.
Um perfil de linguagem uma combinao de mdulos. Os mdulos so atmicos, isto , no podem ser subdivididos quando includos em um perfil de linguagem. Alm disso, a especificao de um mdulo pode incluir um conjunto de requisitos para integrao, com o qual os perfis de linguagem, que incluem o mdulo, devem obrigatoriamente ser compatveis. NCL foi especificada de forma modular, permitindo a combinao de seus mdulos em perfis de linguagem. Cada perfil pode agrupar um subconjunto de mdulos NCL, permitindo a criao de linguagens voltadas para as necessidades especficas dos usurios. Alm disso, os mdulos e perfis NCL podem ser combinados com mdulos definidos em outras linguagens, permitindo a incorporao de caractersticas da NCL naquelas linguagens e vice-versa. Normalmente, h um perfil de linguagem que incorpora quase todos os mdulos associados a um nico namespace. Esse o caso do perfil Linguagem NCL. Outros perfis de linguagem podem ser especificados como subconjuntos de um perfil maior ou incorporar uma combinao de mdulos associados a diferentes namespaces. Exemplos do primeiro caso so os perfis TVD Bsico (perfil BDTV) e TVD Avanado (perfil EDTV) da NCL. Subconjuntos dos mdulos do perfil Linguagem NCL utilizados na definio dos perfis TVD Bsico e TVD Avanado so definidos, para ajustar a linguagem s caractersticas do ambiente de radiodifuso de televiso, com seus vrios dispositivos de apresentao: aparelho de televiso, dispositivos mveis etc.
NOTA Uma abordagem similar tambm encontrada em outras linguagens (SMIL 2.1 Specification:2005 e XHTML 1.0:2002).
O principal objetivo da conformidade com perfis de linguagem aumentar a interoperabilidade. Os mdulos obrigatrios so definidos de forma que qualquer documento, especificado em conformidade com um perfil de linguagem, resulta em uma apresentao razovel quando apresentado em um perfil distinto daquele para o qual foi especificado. O formatador de documentos, suportando o conjunto de mdulos obrigatrios, ignoraria todos os outros elementos e atributos desconhecidos.
NOTA Renderizador de documentos, agente do usurio e exibidor so outros nomes atribudos ao formatador de documentos.
28
A verso NCL 3.0 revisa as funcionalidades contidas na NCL 2.3 (NCL Main Profile:2005) e particionada em 15 reas funcionais, que so novamente particionadas em mdulos. A partir das 15 reas funcionais, 14 so utilizadas para definir os perfis TVD Avanado e TVD Bsico. Duas reas funcionais tm mdulos com a mesma semntica definida por SMIL 2.0. As 14 reas funcionais utilizadas e seus mdulos correspondentes so: 1) Structure
Mdulo MediaContentAnchor Mdulo CompositeNodeInterface Mdulo PropertyAnchor Mdulo SwitchInterface 5) Presentation Specification
Mdulo ConnectorCommonPart Mdulo ConnectorAssessmentExpression Mdulo ConnectorCausalExpression Mdulo CausalConnector Mdulo CausalConnectorFunctionality Mdulo ConnectorBase 8) Presentation Control
29
Mdulo Animation 13) Transition Effects Mdulo TransitionBase Mdulo Transition 14) Meta-Information Mdulo Metainformation 7.1.2 Identificadores para mdulos e perfis de linguagem da NCL 3.0
Recomenda-se que cada perfil NCL declare explicitamente o URI do namespace que ser usado para identific-lo. Documentos criados em perfis de linguagem que incluem o mdulo Structure de NCL podem ser associados com o tipo MIME application/x-ncl+xml. Os documentos utilizando o tipo MIME application/x-ncl+xml devem obrigatoriamente estar em conformidade com a linguagem hospedeira. Os identificadores de namespace XML para o conjunto completo de mdulos, elementos e atributos NCL 3.0 esto contidos no seguinte namespace: http://www.ncl.org.br/NCL3.0/. Cada mdulo NCL possui um identificador nico a ele associado. Os identificadores dos mdulos NCL 3.0 devem obrigatoriamente estar de acordo com a Tabela 7. Mdulos tambm podem ser identificados coletivamente. As seguintes colees de mdulos so definidas: mdulos utilizados pelo perfil Linguagem NCL 3.0: http://www.ncl.org.br/NCL3.0/LanguageProfile; mdulos utilizados pelo perfil Conector Causal NCL 3.0: http://www.ncl.org.br/NCL3.0/CausalConnectorProfile; mdulos utilizados pelo perfil DTV Avanado NCL 3.0: http://www.ncl.org.br/NCL3.0/EDTVProfile; mdulos utilizados pelo perfil DTV Bsico NCL 3.0: http://www.ncl.org.br/NCL3.0/BDTVProfile.
30
Tabela 7 Identificadores dos mdulos de NCL 3.0 Mdulos Animation CompositeNodeInterface CausalConnector CausalConnectorFunctionality ConnectorCausalExpression ConnectorAssessmentExpression ConnectorBase ConnectorCommonPart ContentControl Context Descriptor DescriptorControl EntityReuse ExtendedEntityReuse Import Layout Linking Media MediaContentAnchor KeyNavigation PropertyAnchor Structure SwitchInterface TestRule TestRuleUse Timing TransitionBase Transition Metainformation Identificadores http://www.ncl.org.br/NCL3.0/Animation http://www.ncl.org.br/NCL3.0/CompositeNodeInterface http://www.ncl.org.br/NCL3.0/CausalConnector http://www.ncl.org.br/NCL3.0/CausalConnectorFunctionality http://www.ncl.org.br/NCL3.0/ConnectorCausalExpression http://www.ncl.org.br/NCL3.0/ConnectorAssessmentExpression http://www.ncl.org.br/NCL3.0/ConnectorBase http://www.ncl.org.br/NCL3.0/ConnectorCommonPart http://www.ncl.org.br/NCL3.0/ContentControl http://www.ncl.org.br/NCL3.0/Context http://www.ncl.org.br/NCL3.0/Descriptor http://www.ncl.org.br/NCL3.0/DescriptorControl http://www.ncl.org.br/NCL3.0/EntityReuse http://www.ncl.org.br/NCL3.0/ExtendedEntityReuse http://www.ncl.org.br/NCL3.0/Import http://www.ncl.org.br/NCL3.0/Layout http://www.ncl.org.br/NCL3.0/Linking http://www.ncl.org.br/NCL3.0/Media http://www.ncl.org.br/NCL3.0/MediaContentAnchor http://www.ncl.org.br/NCL3.0/KeyNavigation http://www.ncl.org.br/NCL3.0/PropertyAnchor http://www.ncl.org.br/NCL3.0/Structure http://www.ncl.org.br/NCL3.0/SwitchInterface http://www.ncl.org.br/NCL3.0/TestRule http://www.ncl.org.br/NCL3.0/TestRuleUse http://www.ncl.org.br/NCL3.0/Timing http://www.ncl.org.br/NCL3.0/TransitionBase http://www.ncl.org.br/NCL3.0/Transition http://www.ncl.org.br/NCL3.0/MetaInformation
Trs mdulos SMIL [SMIL 2.1 Specification, 2005] foram usados como base para a definio dos mdulos NCL Transition e Metainformation. Os identificadores desses mdulos SMIL 2.0 so apresentados na Tabela 8. Tabela 8 - Identificadores dos mdulos de SMIL 2.0 Modules BasicTransitions TransitionModifiers Metainformation Identifiers http://www.w3.org/2001/SMIL20/BasicTransitions http://www.w3.org/2001/SMIL20/TransitionsModifiers http://www.w3.org/2001/SMIL20/Metainformation
31
7.1.3
As seguintes instrues de processamento devem obrigatoriamente ser includas em um documento NCL. Elas identificam documentos NCL que contenham apenas os elementos definidos nesta Norma, e a verso NCL com a qual o documento est de acordo. <?xml version="1.0" encoding="ISO-8859-1"?> <ncl id="qualquer string" xmlns="http://www.ncl.org.br/NCL3.0/profileName"> O atributo id do elemento <ncl> pode receber qualquer cadeia de caracteres como valor. O nmero de verso de uma especificao NCL consiste em um nmero principal e outro secundrio, separados por um ponto. Os nmeros so representados como uma cadeia de caracteres formada por nmeros decimais, na qual os zeros esquerda so suprimidos. O nmero de verso inicial do padro 3.0. Novas verses da NCL devem obrigatoriamente ser publicadas de acordo com a seguinte poltica de versionamento: se os receptores compatveis com verses mais antigas ainda puderem receber um documento com base na especificao revisada, com relao a correes de erro ou por motivos operacionais, a nova verso da NCL deve obrigatoriamente ser publicada com o nmero secundrio atualizado; se os receptores compatveis com verses mais antigas no puderem receber um documento baseado nas especificaes revisadas, o nmero principal deve obrigatoriamente ser atualizado. Uma verso especfica est definida sob o URI http://www.ncl.org.br/NCL3.0/profileName, onde o nmero da verso escrito imediatamente aps a sigla NCL. O nome do perfil (profileName) no URI deve obrigatoriamente ser EDTVProfile (Perfil TVD Avanado) ou BDTVProfile (Perfil TVD Bsico).
7.2
7.2.1
Mdulos NCL
Observaes gerais
As principais definies de cada um dos mdulos NCL 3.0 presentes nos perfis NCL TVD Bsico e TVD Avanado so dadas em 7.2.2 a 7.2.15. A definio completa dos mdulos NCL 3.0, utilizando XML Schema, apresentada no Anexo A. Qualquer ambigidade encontrada neste texto pode ser esclarecida por meio da consulta aos esquemas XML. Aps discutir cada mdulo, uma tabela apresentada para indicar os elementos do mdulo e seus atributos. Para um dado perfil, os atributos e contedos (elementos filhos) dos elementos podem ser definidos no prprio mdulo ou no perfil da linguagem que agrupa os mdulos. As tabelas descritas em 7.2.2 a 7.2.15 mostram os atributos e contedos que vm do perfil NCL DTV Avanado, alm dos definidos nos prprios mdulos. As tabelas descritas em 7.3.3 mostram os atributos e contedos que vm do perfil NCL TVD Bsico, alm dos definidos nos prprios mdulos. Os atributos de elementos que so obrigatrios esto sublinhados. Nas tabelas, os seguintes smbolos so empregados: (?) opcional (zero ou uma ocorrncia), (|) ou, (*) zero ou mais ocorrncias, (+) uma ou mais ocorrncias. A ordem dos elementos filhos no especificada nas tabelas.
32
7.2.2
A rea funcional Structure tem apenas um mdulo, chamado Structure, que define a estrutura bsica de um documento NCL. Essa rea define o elemento raiz, chamado <ncl>, o elemento <head> e o elemento <body>, seguindo a terminologia adotada por outros padres W3C. O elemento <body> de um documento NCL tratado como um n de contexto NCM (NCMCore:2005). No NCM, o modelo conceitual de dados da NCL, um n pode ser um contexto, um switch ou um objeto de mdia. Todos os ns NCM so representados por elementos NCL correspondentes. Os ns de contexto, conforme definido em 7.2.4, contm outros ns e elos NCM. Os elementos <ncl> e <body> podem definir um atributo id. O atributo id identifica univocamente um elemento dentro de um documento. Seu valor um identificador XML. O atributo title de <ncl> oferece informao adicional sobre o elemento. Os valores do atributo title podem ser utilizados por agentes de usurios de vrias formas. O atributo xmlns declara um namespace XML, isto , ele declara a coleo primria de construes XML utilizada pelo documento. O valor do atributo o URL (Uniform Resource Locator), que identifica onde o namespace est oficialmente definido. Trs valores so permitidos para o atributo xmlns: http://www.ncl.org.br/NCL3.0/EDTVProfile e http://www.ncl.org.br/NCL3.0/BDTVProfile, para os perfis TVD Avanado e Bsico, respectivamente, e http://www.ncl.org.br/NCL3.0/CausalConnectorProfile, para o perfil Conector Causal. Um formatador NCL deve obrigatoriamente saber que a localizao dos esquemas para tais namespaces , por default, respectivamente: http://www.ncl.org.br/NCL3.0/profiles/NCL30EDTV.xsd, http://www.ncl.org.br/NCL3.0/profiles/NCL30BDTV.xsd, e http://www.ncl.org.br/NCL3.0/profiles/NCL30CausalConnector.xsd Os elementos filhos de <head> e <body> so definidos em outros mdulos NCL. fortemente recomendado que os elementos filhos de <head> sejam declarados na seguinte ordem: importedDocumentBase?, ruleBase?, transitionBase?, regionBase*, descriptorBase?, connectorBase?, meta*, metadata*. Os elementos deste mdulo, seus elementos filhos e seus atributos devem obrigatoriamente estar de acordo com a Tabela 9. Tabela 9 Mdulo Structure estendido Elementos ncl head Atributos id, title, xmlns (head?, body?) (importedDocumentBase?, ruleBase?, transitionBase?, regionBase*, descriptorBase?, connectorBase?, meta*, metadata*) id (port| property| media| context| switch| link | meta | metadata)* Contedo
body
7.2.3
A rea funcional Layout tem um nico mdulo, chamado Layout, o qual especifica elementos e atributos que definem como os objetos sero inicialmente apresentados dentro de regies de dispositivos de sada. De fato, este mdulo define valores iniciais para propriedades NCL homnimas definidas nos elementos <media>, <body> e <context> (ver 7.2.4).
33
Um elemento <regionBase>, que deve obrigatoriamente ser declarado no elemento <head> do documento NCL, define um conjunto de elementos <region>, cada qual podendo conter outro conjunto de elementos <region> aninhados, e assim por diante, recursivamente. O elemento <regionBase> pode ter um atributo id. Elementos <region> devem obrigatoriamente ter um atributo id. Como esperado, o atributo id identifica univocamente um elemento dentro de um documento. Cada elemento <regionBase> est associado a uma classe de dispositivos onde acontecer a apresentao. Para identificar a associao, o elemento <regionBase> define o atributo device, que pode ter os valores: systemScreen (i) ou systemAudio(i). A classe escolhida define as variveis globais do ambiente: system.screenSize(i), system.screenGraphicSize(i) e system.audioType(i), como definido na Tabela 12 (ver 7.2.4). Quando o atributo no especificado, a apresentao deve obrigatoriamente ser feita no mesmo dispositivo que executa o formatador NCL.
NOTA 1 Existem dois diferentes tipos de classes de dispositivos: activa e passiva. Em uma classe ativa, um dispositivo capaz de executar as funes de exibidores de mdia. De um dispositivo de exibio que se cadastra em uma classe do tipo passiva no exigida a capacidade de executar as funes de exibidores de mdia. Ele deve ser capaz apenas de apresentar o mapa de memria de vdeo que lhe passado e exibir as amostras de udio que lhe so passadas por um outro dispositivo. No SBTVD, systemScreen (1) e systemAudio (1) so reservados para classes do tipo passiva; systemScreen (2) e systemAudio (2) so reservados para classes do tipo ativa. NOTA 2 O elemento <regionBase> que define uma classe passiva pode tambm ter um atributo region. Esse atributo usado para identificar um elemento <region> em uma outra <regionBase> associada a uma classe ativa onde est registrado o dispositivo que gera o mapa de memria de vdeo enviado para os dispositivos da classe passiva; na regio especificada, o mapa de memria tambm deve ser exibido.
Recomenda-se que a interpretao do aninhamento das regies dentro de um <regionBase> seja feita pelo software responsvel pela orquestrao da apresentao do documento (isto , o formatador NCL). Para os efeitos desta Norma, um primeiro nvel de aninhamento deve obrigatoriamente ser interpretado como se fosse a rea do dispositivo onde a apresentao ocorrer; o segundo nvel como janelas (por exemplo, reas de apresentao na tela) da rea-pai; e os outros nveis como regies dentro dessas janelas. Uma <region> pode tambm definir os seguintes atributos: title, left, right, top, bottom, height, width e zIndex. Todos esses atributos possuem o significado usual W3C. A posio de uma regio, conforme especificada por seus atributos top, bottom, left e right, sempre relativa geometria-pai, que definida pelo elemento <region> pai ou pela rea total do dispositivo, no caso das regies no primeiro nvel de aninhamento. Os valores dos atributos podem ser valores percentuais no-negativos, ou unidades de pixels. Para valores em pixels, o autor pode omitir o qualificador de unidade px (por exemplo, 100). Para valores percentuais, por outro lado, o smbolo % deve obrigatoriamente ser indicado (por exemplo, 50%). O percentual sempre relativo largura do pai, no caso das definies dos atributos right, left and width, e altura do pai, para as definies dos atributos bottom, top e height. Os atributos top e left so os atributos primrios de posicionamento da regio. Eles posicionam o canto superior esquerdo da regio na distncia especificada a partir da margem superior esquerda da regio-pai (ou margem superior esquerda do dispositivo, no caso da regio no primeiro nvel de aninhamento). Algumas vezes, ajustar explicitamente os atributos bottom e right pode ser til. Seus valores estabelecem a distncia entre o canto inferior direito da regio e o canto inferior direito da regio-pai (ou a margem inferior direita do dispositivo, no caso da regio no primeiro nvel de aninhamento) (ver Figura 2).
34
left top
width
right
height
region
bottom
parent region
Figura 2 Atributos de posicionamento da regio Com relao aos tamanhos da regio, quando eles so especificados declarando os atributos width e height usando a notao "%", o tamanho da regio relativo ao tamanho da geometria de seu pai, como mencionado anteriormente. Os tamanhos declarados como valores absolutos em pixels mantm tais valores absolutos. O tamanho intrnseco de uma regio igual ao tamanho da geometria lgica do pai. Isso significa que, se uma regio aninhada no especificar qualquer posicionamento ou valores de tamanho, deve ser obrigatoriamente assumido que ela tem a mesma posio e valores de tamanho que sua regio-pai. Em particular, quando uma regio de primeiro nvel no especifica qualquer posicionamento ou valores de tamanho, deve ser obrigatoriamente assumida como tendo toda a rea de apresentao do dispositivo. Quando o usurio especifica informaes sobre top, bottom e height para uma mesma <region>, podem ocorrer inconsistncias espaciais. Neste caso, os valores de top e height devem obrigatoriamente preceder o valor de bottom. De forma anloga, quando o usurio especifica valores inconsistentes para os atributos left, right e width da <region>, os valores de left e width devem obrigatoriamente ser utilizados para calcular um novo valor de right. Quando qualquer um desses atributos no especificado e no pode ter seu valor calculado a partir de outros atributos, esse valor deve obrigatoriamente ser herdado do valor correspondente definido no pai dessa <region>. Outra restrio que as regies-filhas no podem ficar fora da rea estabelecida por suas regies-pais. O atributo zIndex especifica a precedncia de sobreposio da regio. Regies com maiores valores de zIndex devem ser obrigatoriamente empilhadas no topo de regies com valores de zIndex menores. Se duas apresentaes geradas pelos elementos A e B tiverem o mesmo nvel de empilhamento, caso a exibio de um elemento B comece depois da exibio de um elemento A, a apresentao de B deve obrigatoriamente ser empilhada no topo da apresentao de A (ordem temporal); por outro lado, se a exibio dos elementos comear ao mesmo tempo, a ordem empilhada escolhida arbitrariamente pelo formatador. Quando omitido, o valor default do zIndex igual a 0 (zero). O mdulo Layout tambm define o atributo region, que utilizado por um elemento <descriptor> (ver 7.2.6) para referir-se a um elemento <region> de Layout. Os elementos deste mdulo, seus elementos-filhos e seus atributos devem obrigatoriamente estar de acordo com a Tabela 10. Tabela 10 Mdulo Layout estendido Elementos regionBase region Atributos id, device, region id, title, left, right, top, bottom, height, width, zIndex Contedo (importBase|region)+ (region)*
35
7.2.4
A rea funcional Components particionada em dois mdulos, chamados Media e Context. O mdulo Media define os tipos bsicos de objetos de mdia. Para definir objetos de mdia, este mdulo define o elemento <media>. Cada objeto de mdia tem dois atributos principais, alm do atributo id: src, que define um URI do contedo do objeto, e type, que define o tipo de objeto. Os URI (Uniform Resource Identifier) devem obrigatoriamente estar de acordo com a Tabela 11. Tabela 11 URI permitidos Esquema file: http: Parte especifica do esquema ///file_path/#fragment_identifier //server_identifier/file_path/#fragment_identifier Uso Para arquivos locais Para arquivos remotos buscados pelo canal de interatividade usando o protocolo http Para arquivos remotos buscados pelo canal de interatividade usando o protocolo https Para fluxos (streams) obtidos pelo canal de interatividade usando o protocolo rstp Para fluxos (streams) obtidos pelo canal de interatividade usando o protocolo rtp Para um fluxo de contedo idntico a um que esteja em apresentao por um outro elemento de mdia Para fluxos elementares recebidos pelo fluxo de transporte (TS)
https
//server_identifier/file_path/#fragment_identifier
rstp:
//server_identifier/file_path/#fragment_identifier
//server_identifier/file_path/#fragment_identifier
//media_element_identifier //program_number.component_tag
Um URI absoluto contm todas as informaes necessrias para localizar seu recurso. Os URI relativos tambm so permitidos. URI relativos so endereos incompletos que so aplicados a um URI base para completar a localizao. As partes omitidas so o esquema URI, o servidor e, tambm, em alguns casos, parte do caminho do URI. O benefcio principal de utilizar URI relativas a possibilidade de mover ou copiar para outros locais os documentos e diretrios contidos no URI, sem exigir a troca dos valores dos atributos URI dentro dos documentos. Isso especialmente interessante quando se transportam documentos do servidor (normalmente radiodifusores) para os receptores. Os caminhos relativos do URI so tipicamente utilizados como um meio rpido de localizao de arquivos de mdia armazenados no mesmo diretrio do documento NCL atual, ou em um diretrio prximo a ele. Eles frequentemente consistem apenas no nome do arquivo (opcionalmente com um identificador de fragmento dentro do arquivo). Eles tambm podem ter um caminho relativo de diretrio antes do nome do arquivo. Convm enfatizar que as referncias para os recursos de fluxos de vdeo ou udio no devem, obrigatoriamente, causar a ocorrncia de sintonizao (tuning). As referncias que implicam sintonizao para acessar um recurso devem obrigatoriamente se comportar como se o recurso estivesse indisponvel. Os valores permitidos para o atributo type dependem do perfil NCL e devem obrigatoriamente seguir o formato MIME Media Types (ou, simplesmente, mimetypes). Um mimetype uma cadeia de caracteres que define a classe da mdia (udio, vdeo, imagem, texto, aplicao) e um tipo de codificao de mdia (como jpeg, mpeg etc.). Os mimetypes podem ser registrados ou informais. Os mimetypes registrados so controlados pela IANA (Internet Assigned Numbers Authority). Os mimetypes informais no so registrados pela IANA, mas so definidos em comum acordo; eles normalmente tm um x- antes do nome do tipo de mdia. Cinco tipos especiais so definidos: application/x-ginga-NCL; application/x-ginga-NCLua, application/x-gingaNCLet, application/x-ginga-settings e application/x-ginga-time.
36
O tipo application/x-ginga-NCL deve obrigatoriamente ser aplicado a elementos <media> com cdigo NCL (assim, uma aplicao NCL pode ser embutida em outra aplicao NCL). O tipo application/x-ginga-NCLua deve obrigatoriamente ser aplicado a elementos <media> com cdigo procedural Lua como contedo (ver Seo 10). O tipo application/x-ginga-NCLet deve obrigatoriamente ser aplicado a elementos <media> com cdigo procedural Xlet como contedo (ver Seo 11). O tipo application/x-ginga-settings deve obrigatoriamente ser aplicado a um elemento <media> especial (pode existir somente um em um documento NCL) cujas propriedades so variveis globais definidas pelo autor do documento ou variveis de ambiente reservadas, que podem ser manipuladas pelo processamento do documento NCL. A Tabela 12 estabelece as variveis j definidas e sua semntica. Tabela 12 Variveis de ambiente
Grupo Varivel system.language system.caption system.subtitle system.returnBitRate(i) system.screenSize Semntica Linguagem de udio Linguagem de caption Linguagem de legenda Taxa de bits do canal de interatividade (i) em Kbps Tamanho da tela do dispositivo de exibio, em (linhas, pixels/linha), quando uma classe no for definida Resoluo configurada para o plano grfico da tela do dispositivo de exibio, em (linhas, pixels/linha), quando uma classe no for definida Tipo de udio do dispositivo de exibio, quando uma classe no for definida Tamanho da tela da classe (i) de dispositivos de exibio, em (linhas, pixels/linha) Resoluo configurada para o plano grfico da tela da classe (i) de dispositivos de exibio, em (linhas, pixels/linha) Tipo de udio da classe (i) de dispositivos de exibio Nmero de dispositivos de exibio cadastrados na classe (i) Tipo da classe (i) Lista de exibidores de mdia da classe (i) de dispositivos de exibio Nmero de classes de dispositivos de exibio definidas Desempenho da CPU em MIPS Espao da memria em Mbytes Tipo de sistema operacional Tipo e verso da configurao suportada pela JVM do receptor Valores possveis ISO 639-1 code ISO 639-1 ISO 639-1 real (inteiro, inteiro)
system.screenGraphicSize
(inteiro, inteiro)
system.audioType system grupo de variveis mantidas pelo sistema receptor; system.screenSize (i)
podem ser lidas, mas no podem ter seus valores alterados por um aplicativo system.audioType(i) NCL, um procedimento Lua ou um procedimento Xlet; system.devNumber(i) programas nativos no receptor podem alterar os valores das variveis; persistem durante todo o tempo de vida de um receptor system.classType(i) system.info(i) system.classNumber system.CPU system.memory
system.screenGraphicSize (i)
(inteiro, inteiro)
mono | stereo | 5.1 inteiro (passive | ative) string inteiro real inteiro string a ser definida string (tipo seguido da verso, sem espao, por exemplo: CLDC1.1) string (tipo seguido da verso, sem espao ex.: MIDP2.0
system.operatingSystem
system.javaConfiguration
system.javaProfile
system.luaVersion system.xxx
Verso da mquina Lua do receptor Qualquer varivel prefixada por system deve obrigatoriamente ser reservada para uso futuro
string
37
Tabela 12 (continuao)
Grupo Varivel Semntica Valores possveis white | black | silver | gray | red | maroon | fuchsia | purple | lime | green | yellow | olive | blue | navy | aqua | teal white | black | silver | gray | red | maroon | fuchsia | purple | lime | green | yellow | olive | blue | navy | aqua | teal
default.focusBorderColor default grupo de variveis mantidas pelo sistema receptor; default.selBorderColor podem ser lidas e ter seus valores alterados por um aplicativo NCL ou por um procedimento Lua ou Xlet; default.focusBorderWidth programas nativos no receptor podem alterar os valores das variveis; persistem durante todo o tempo de vida de um receptor, no entanto, voltam ao seu valor inicial quando da troca de canais
inteiro
default.focusBorderTransparency
valor real entre 0 e 1, ou valor real na faixa [0,100] terminando com o caractere % (por exemplo, 30 %), com 1, ou 100 % significando mxima transparncia e 0, ou 0 % significando nenhuma transparncia
default.xxx
Qualquer varivel prefixada por default deve obrigatoriamente ser reservada para uso futuro Valor do atributo focusIndex do elemento <media> em foco Identificador (id) do elemento <media> que detm o controle das chaves de navegao; se o elemento no estiver sendo apresentado ou no estiver pausado, o controle do formatador inteiro
service grupo de variveis mantidas pelo formatador NCL; podem ser lidas e, em geral, ter seus valores alterados por um aplicativo NCL do mesmo servio; podem ser lidas, mas no podem ter seus valores alterados por um programa Lua ou Xlet do mesmo servio; a escrita deve ser atravs de comandos NCL;
service.currentFocus
service.currentKeyMaster
string
Qualquer varivel prefixada por service deve obrigatoriamente seguir as regras especificadas para o grupo
38
Tabela 12 (continuao)
Grupo si grupo de variveis mantidas pelo middleware; podem ser lidas, mas no podem ter seus valores alterados por um aplicativo NCL, um procedimento Lua ou um procedimento Xlet; persistem, no mnimo, durante todo o tempo de sintonia de um canal Varivel Semntica Nmero de servios disponveis, no pas, para o canal sintonizado. NOTA recomendado que o valor dessa varivel seja obtido a partir do nmero de tabelas PMT encontradas na tabela PAT do fluxo de transporte recebido pelo canal sintonizado (conforme norma ISO/IEC 13818-1:2007). No clculo do valor dessa varivel, recomendado que apenas sejam consideradas as tabelas cujo campo country_code, disponvel no descritor country_availability_descriptor (Seo 8.3.6 da norma ABNT NBR 15603-2:2007) relativo tabela, corresponder ao contedo da varivel de ambiente user.location. Nmero de servios 1-seg disponveis, no pas, para o canal sintonizado. NOTA recomendado que o valor dessa varivel seja obtido a partir do nmero de tabelas PMT encontradas na tabela PAT do fluxo de transporte recebido pelo canal sintonizado (conforme ISO/IEC 13818-1:2007). No clculo do valor dessa varivel, recomendado que apenas sejam consideradas as tabelas PMT cujo campo country_code, disponvel no descritor country_availability_descriptor (Seo 8.3.6 da ABNT NBR 15603-2:2007), corresponder ao contedo da varivel de ambiente user.location, e tambm cujos campos program_number das tabelas correspondam aos campos service_id dos partial_reception_descriptor relativos s tabelas NIT. Nmero do canal sintonizado. NOTA O valor desta varivel deve obrigatoriamente ser obtido atravs do campo remote_control_key_id do descritor ts_information_descriptor (Seo 8.3.42 da norma ABNT NBR 15603-2:2007) da tabela NIT (Seo 7.2.4 da norma ABNT NBR 156032:2007) que descreve o servio corrente. Qualquer varivel prefixada por si deve obrigatoriamente seguir as regras especificadas para o grupo Valores possveis
si.numberOfServices
inteiro
si.numberOfPartialServices
inteiro
si.channelNumber
inteiro
si.xxx
39
Tabela 12 (concluso)
Grupo channel grupo de variveis mantidas pelo formatador NCL; podem ser lidas e ter seus valores alterados por um aplicativo NCL do mesmo canal; podem ser lidas, mas no podem ter seus valores alterados por um programa Lua ou Xlet do mesmo canal; a escrita deve ser atravs de comandos NCL; persistem, no mnimo, durante todo o tempo de sintonia de um canal shared grupo de variveis mantidas pelo formatador NCL; podem ser lidas e ter seus valores alterados por um programa NCL; podem ser lidas, mas no podem ter seus valores alterados por um programa Lua ou Xlet; a escrita deve ser atravs de comandos NCL; persistem, no mnimo, durante todo o tempo do servio que a definiu shared.xxx Varivel channel.keyCapture Semntica Requisio de teclas alfanumricas por aplicaes NCL Requisio do teclado virtual por aplicaes NCL Regio de exibio do teclado virtual (left, top, width, height) Qualquer varivel prefixada por channel deve obrigatoriamente seguir as regras especificadas para o grupo Valores possveis (true | false)
channel.virtualKeyboard channel.keyboardBounds
channel.xxx
Qualquer varivel prefixada por shared deve obrigatoriamente seguir as regras especificadas para o grupo
O tipo application/x-ginga-time deve obrigatoriamente ser aplicado a um elemento <media> especial (pode existir somente um em um documento NCL) cujo contedo o Universal Time Coordinated (UTC). Qualquer elemento <media> contnuo sem fonte pode ser utilizado para definir um relgio, relativo ao tempo de incio desse elemento <media>.
NOTA O contedo de um elemento <media> do tipo application/x-ginga-time especificado com a seguinte sintaxe: Ano:Ms:Dia:Hora:Minutos:Segundos.Frao, onde Ano um inteiro; Ms um inteiro no intervalo [1,12]; Dia um inteiro no intervalo [1,31]; Horas um inteiro no intervalo [0, 23]; Minutos um inteiro no intervalo [0,59]; Segundos um inteiro no intervalo [0,59]; e Frao um inteiro positivo.
A Tabela 13 mostra alguns valores possveis do atributo type para os perfis TVD Avanado e Bsico e as extenses de arquivos associadas. Os tipos obrigatrios so definidos na ABNT NBR 15601. O atributo type opcional (exceto para os elementos <media> sem atributo src definido) e recomenda-se ser usado para guiar a escolha do exibidor de mdia (ferramenta de apresentao) pelo formatador. Quando o atributo type no especificado, recomenda-se que o formatador use a extenso do contedo especificado no atributo src para fazer a escolha do exibidor. Quando h mais que um exibidor para o tipo suportado pelo formatador, o elemento <descriptor> pode especificar qual ser utilizado para a apresentao. Caso contrrio, o formatador deve obrigatoriamente utilizar um exibidor default para aquele tipo de mdia.
40
text/plain text/css text/xml image/bmp image/png image/gif image/jpeg audio/basic audio/mp3 audio/mp2 audio/mpeg audio/mpeg4 video/mpeg application/x-ginga-NCL application/x-ginga-NCLua
application/x-ginga-NCLet application/x-ginga-settings application/x-ginga-time
mp3 mp2 mpeg, mpg mp4, mpg4 mpeg, mpg ncl lua
class, jar
O mdulo Context responsvel pela definio de ns de contexto atravs de elementos <context>. Um n de contexto NCM um tipo particular de n de composio NCM e definido contendo um conjunto de ns e um conjunto de elos. Como normalmente ocorre, o atributo id identifica univocamente cada elemento <context> e <media> dentro de um documento. Os atributos Instance, refer e descriptor so extenses definidas em outros mdulos e so discutidos na definio de tais mdulos.
NOTA Elementos <media> do tipo application/x-ginga-NCL recomendado que eles tambm no tenham elementos filho. no podem ter os atributos instance e refer.
Os elementos dos dois mdulos da funcionalidade Components, seus elementos-filhos e seus atributos devem obrigatoriamente estar de acordo com as Tabelas 14 e 15. Tabela 14 Mdulo Media estendido Elements media Attributes id, src, refer, instance, type, descriptor (area|property)* Content
Tabela 15 Mdulo Context estendido Elements context Attributes id, refer Content (port|property|media|context|link|switch|meta|metadata)*
41
7.2.5
A rea funcional Interfaces permite a definio de interfaces de ns (objetos de mdia ou ns de composio) que sero utilizadas em relacionamentos com outras interfaces de ns. Esta rea funcional particionada em quatro mdulos: MediaContentAnchor, que permite definies de ncoras de contedo (ou rea) para ns de mdia (elementos <media>); CompositeNodeInterface, que permite definies de portas para ns de composio (elementos <context> e <switch>); PropertyAnchor, que permite a definio de propriedades de ns como interfaces de ns; e SwitchInterface, que permite a definio de interfaces especiais para elementos <switch>. O mdulo MediaContentAnchor define o elemento <area>, que estende a sintaxe e semntica do elemento homnimo definido por SMIL e XHTML. Assim, ele permite a definio de ncoras de contedo representando pores espaciais, atravs de atributo coords (como em XHTML); a definio de ncoras de contedo representando pores temporais, atravs dos atributos begin e end; e a definio de ncoras de contedo representando pores espao-temporais atravs dos atributos coords, begin e end (como em SMIL). Alm disso, o elemento <area> permite a definio de ncoras textuais, atravs dos atributos text e position, que definem uma cadeia de caracteres e a ocorrncia dessa cadeia no texto, respectivamente. Adicionalmente, o elemento <area> pode tambm definir uma ncora de contedo com base no nmero de amostras de udio ou frames de vdeo, atravs dos atributos first e last, que devem obrigatoriamente indicar a amostra/frame inicial e final. Finalmente, o elemento <area> tambm pode definir uma ncora de contedo baseada no atributo label, que especifica uma cadeia de caracteres que deve ser utilizada pelo exibidor de mdias para identificar uma regio de contedo.
NOTA Os atributos first e last so especificados de acordo com uma das seguintes sintaxes:
a) Amostrass, onde Amostras um inteiro positivo; b) Quadrosf, onde Quadros um inteiro positivo; c) NPTnpt, onde NPT o valor tempo normal de exibio (Normal Play Time value).
Se o atributo begin for definido, mas o atributo end no for especificado, o final de toda apresentao do contedo de mdia deve obrigatoriamente ser considerado como encerramento da ncora. Por outro lado, se o atributo end for definido sem uma definio explcita de begin, o incio de toda a apresentao do contedo de mdia deve obrigatoriamente ser considerado como o incio da ncora. Comportamento semelhante esperado com relao aos atributos first e last. No caso de um elemento <media> do tipo application/x-ginga-time, os atributos begin e end devem obrigatoriamente ser sempre especificados e correspondem a um tempo absoluto do Universal Time Coordinated (UTC).
NOTA 1 Com exeo do elemento <media> do tipo application/x-ginga-time, os atributos begin e end devem obrigatoriamente ser especificados com uma das seguintes sintaxes: a) Horas:Minutos:Segundos.Frao, onde Horas um inteiro no intervalo [0,23]; Minutos um inteiro no intervalo [0,59]; Segundos um inteiro no intervalo [0,59]; e Frao um inteiro positivo b) Segundoss, onde Segundos um inteiro positivo. NOTA 2 Para o elemento <media> do tipo application/x-ginga-time, os atributos begin e end devem pbrigatoriamente ser especificados de acordo com a seguinte sintaxe: Ano:Ms:Dia:Hora:Minutos:Segundos.Frao, de acordo com a zona do tempo do pas. O Formatador NCL responsvel por traduzir esse valor para um valor correspondente de UTC.
Como normalmente ocorre, os elementos <area> devem obrigatoriamente ter um atributo id, que identifica univocamente o elemento dentro de um documento. O elemento <area> e seus atributos devem obrigatoriamente estar de acordo com a Tabela 16.
42
Tabela 16 Mdulo MediaContentAnchor estendido Elementos area Atributos id, coords, begin, end, text, position, first, last, label Contedo vazio
O mdulo CompositeNodeInterface define o elemento <port>, que especifica uma porta de um n de composio com seu respectivo mapeamento para uma interface (atributo interface) de um de seus componentes (especificado pelo atributo component). No NCM, todo n (mdia ou contexto) deve obrigatoriamente possuir uma ncora com uma regio representando o contedo total do n. Essa ncora chamada de ncora de contedo total e declarada por omisso (default) em NCL. Cada vez que um componente NCL referenciado sem especificar uma de suas ncoras, deve-se obrigatoriamente assumir a ncora de contedo total. O elemento <port> e seus atributos devem obrigatoriamente estar de acordo com a Tabela 17. Tabela 17 Mdulo CompositeNodeInterface estendido Elementos port Atributos id, component, interface Contedo vazio
O mdulo PropertyAnchor define um elemento chamado <property>, que pode ser utilizado para definir uma propriedade ou grupo de propriedades de um n, como uma de suas interfaces (ncora). O elemento <property> define o atributo name, que indica o nome da propriedade ou grupo de propriedades, e o atributo value, atributo opcional que define um valor inicial para a propriedade name. O elemento pai no pode ter elementos <property> com os mesmos valores para o atributo name. possvel ter exibidores de documentos NCL (formatadores) que definem algumas propriedades de ns e interfaces de ns, implicitamente. Entretanto, em geral, de boa prtica definir explicitamente as interfaces. Assim, todas as interfaces devem obrigatoriamente ser explicitamente definidas. Os elementos <body>, <context> e <media> podem ter vrias propriedades embutidas. Exemplos dessas propriedades podem ser encontrados entre aquelas que definem o local a ser colocado o objeto de mdia durante uma apresentao, a durao da apresentao e outras que definem caractersticas adicionais da apresentao: top, left, bottom, right, width, height, plan, explicitDur, background, transparency, visible, fit, scroll, style, soundLevel, balanceLevel, trebleLevel, bassLevel, fontColor, fontFamily, fontStyle, fontSize, fontVariant, fontWeight, reusePlayer, playerLife etc. Tais propriedades assumem como seus valores iniciais os definidos em atributos homnimos do descritor e regio associado ao n (ver 7.2.3 e 7.2.6). Algumas propriedades tm o seu valor definido pelo prprio sistema, como a propriedade contentId, associada a um objeto de mdia contnua cujo contedo se refere a um fluxo elementar, que inicialmente tem o valor nulo, mas assim que o objeto iniciado assume o valor do identificador (contido no campo tambm chamado contentId) transportado no descritor de referncia NPT. Outro exemplo a propriedade standby que deve obrigatoriamente assumir o valor true enquanto um objeto de mdia contnua j iniciado, cujo contedo se refere a um fluxo elementar, estiver com seu fluxo temporariamente interrompido por outro contedo entrelaado no mesmo fluxo elementar. Entretanto, em qualquer que seja o caso, quando uma propriedade embutida utilizada em um relacionamento, ela deve obrigatoriamente ser explicitamente declarada como elemento <property> (interface).
NOTA 1 propriedade de standby pode ser atribudo o valor true quando o valor do identificador transportado no NPT reference descriptor (no campo contentId) sinalizado como no pausado for diferente do valor da propriedade contentId do mesmo objeto.
43
NOTA 2 A propriedade visible tambm pode ser associada a um elemento <context> e <body>. Nesses casos, quando a propriedade tiver seu valor igual a true, vale a especificao de visible de cada n filho. Quando tiver o seu valor igual a false, todos os elementos da composio so exibidos de forma invisvel. Em particular, quando um documento tem seu elemento <body> com a propriedade visible = false e seu evento de apresentao no estado= paused, diz-se que a aplicao est em espera (stand-by). Quando uma aplicao entra em stand-by, o vdeo principal do servio volta a ocupar 100 % da dimenso da tela em que exibido e o udio principal a 100 % de seu volume.
Um grupo de propriedades do n tambm pode ser explicitamente declarado como um elemento nico <property> (interface), permitindo que os autores especifiquem o valor de vrias propriedades com uma propriedade nica. Os seguintes grupos devem obrigatoriamente ser reconhecidos por um formatador NCL: location, grouping (left, top), nessa ordem; size, grouping (width, height), nessa ordem; e bounds, grouping (left, top, width, height), nessa ordem. Quando um formatador trata uma alterao em um grupo de propriedade, deve obrigatoriamente apenas testar a consistncia do processo ao seu final. As palavras top, left, bottom, right, width, height, explicitDur, background, transparency, visible, fit, scroll, style, soundLevel, balanceLevel, trebleLevel, bassLevel, fontColor, fontFamily, fontStyle, fontSize, fontVariant, fontWeight, reusePlayer, playerLife, location, size e bounds so palavras reservadas para valores do mesmo atributo name do elemento <property>. O elemento <property> e seus atributos devem obrigatoriamente estar de acordo com a Tabela 18. Tabela 18 Mdulo PropertyAnchor estendido Elementos property name, value Atributos Contedo vazio
O mdulo SwitchInterface permite a criao de interfaces de elemento <switch> (ver 7.2.4), que podem ser mapeadas a um conjunto de interfaces alternativas de ns internos, permitindo a um elo ancorar no componente escolhido quando o <switch> processado (NCM Core:2005). Esse mdulo introduz o elemento <switchPort>, que contm um conjunto de elementos de mapeamento. Um elemento de mapeamento define um caminho a partir do <switchPort> para uma interface (atributo interface) de um dos componentes do <switch> (especificados por seu atributo component). importante mencionar que cada elemento representando uma interface de objeto (<area>, <port>, <property> e <switchPort>) deve obrigatoriamente ter um identificador (atributo id). O elemento <switchPort>, seus elementos-filhos e seus atributos devem obrigatoriamente estar de acordo com a Tabela 19. Tabela 19 Mdulo SwitchInterface estendido Elementos switchPort mapping id component, interface Atributos Contedo mapping+ vazio
44
7.2.6
A rea funcional Presentation Specification tem um nico mdulo chamado Descriptor. O objetivo desse mdulo especificar informaes espao-temporais necessrias para a apresentao de cada componente do documento. Essas informaes so modeladas pelos objetos descritores. O mdulo Descriptor permite a definio de elementos <descriptor>, que contm um conjunto de atributos opcionais, agrupando todas as definies espao-temporais a serem usadas de acordo com o tipo de objeto a ser apresentado. A definio de elementos <descriptor> deve obrigatoriamente ser includa no cabealho do documento, dentro do elemento <descriptorBase>, que especifica o conjunto de descritores de um documento. O elemento <descriptor> deve obrigatoriamente ter o atributo id; e o elemento <descriptorBase> pode ter o atributo id, que, como normalmente ocorre, identifica univocamente os elementos dentro de um documento. Um elemento <descriptor> pode ter atributos temporais: explicitDur e freeze, definidos pelo mdulo Timing (ver 7.2.10); um atributo chamado player, que identifica a ferramenta de apresentao a ser utilizada; um atributo chamado region, que refere-se regio definida pelos elementos do mdulo Layout (ver 7.2.3); atributos para navegao: moveLeft, moveRight, moveUp; moveDown, focusIndex, focusBorderColor; focusBorderWidth; focusBorderTransparency, focusSrc, selBorderColor, e focusSelSrc, definidos pelo mdulo KeyNavigation (ver 7.2.12); e atributos de transio: transIn e transOut (ver 7.2.14).
NOTA Um elemento <descriptor> de um elemento <media> do tipo application/x-ginga-NCL no pode conter o atributo player. Neste caso, um exibidor NCL especfico para cada dispositivo de exibio definido pelo middleware.
Um elemento <descriptor> pode tambm ter elementos <descriptorParam> como elementos filho, que so utilizados para parametrizar o controle da apresentao do objeto associado com o elemento descritor. Esses parmetros podem, por exemplo, redefinir alguns valores de atributos definidos pelos atributos da regio. Eles tambm podem definir novos atributos, tais como plan, em qual plano de uma tela estruturada um objeto ser colocado; rgbChromakey, definido uma cor RGB a ser exibida como transparente; background, especificando a cor de fundo utilizada para preencher a rea de uma regio de exibio da mdia, quando toda a regio no preenchida pela mdia em si; visible, permitindo que a apresentao do objeto seja visualizada ou ocultada; fit, indicando como um objeto ser apresentado; scroll, que permite a especificao de como um autor gostaria de configurar a rolagem em uma regio; transparency, indicando o grau de transparncia da apresentao de um objeto; style, que refere-se a uma folha de estilo [Cascading Style Sheets, 1998] com informaes, por exemplo, para apresentao do texto; alm de especificar atributos para objetos de udio, tais como soundLevel, balanceLevel, trebleLevel e bassLevel. Alm disso, os elementos-filhos <descriptorParam> podem determinar se um novo exibidor deve obrigatoriamente ser instanciado, ou se um exibidor j instanciado deve obrigatoriamente ser utilizado (reusePlayer), e especificar o que acontecer instncia do exibidor no final da apresentao (playerLife). As palavras top, left, bottom, right, width, height, explicitDur, location, size, bounds, background, visible, fit, scroll, style, soundLevel, balanceLevel, trebleLevel, bassLevel, reusePlayer e playerLife so palavras reservadas para valores do atributo name do elemento <descriptorParam>. Os valores possveis para os nomes reservados de parmetros/atributos devem obrigatoriamente estar de acordo com a Tabela 20.
45
background
visible transparency
46
Alm de todos os atributos mencionados, o elemento <descriptor> tambm pode ter atributos definidos na rea funcional transition effects (ver 7.2.14).
NOTA Se forem especificadols vrios valores para um mesmo atributo, o valor definido no elemento <property> tem precedncia sobre o valor definido em um elemento <descriptorParam>, que, por sua vez, tem precedncia sobre o valor definido em um atributo do elemento <descriptor> (incluindo o atributo region).
Alm do elemento <descriptor>, o mdulo Descriptor define um atributo homnimo, que refere-se a um elemento do conjunto de descritores do documento. Quando um perfil de linguagem utiliza o mdulo Descriptor, ele deve obrigatoriamente determinar como os descritores estaro associados com os componentes do documento. Seguindo as diretivas NCM, esta Norma estabelece que o atributo descriptor est associado com qualquer n de mdia atravs de elementos <media> e atravs das extremidades dos elos (elementos <bind>) (ver 8.2.1). O conjunto de descritores de um documento pode conter elementos <descriptor> ou elementos <descriptorSwitch>, que permitem especificar descritores alternativos (ver 7.2.9). Os elementos do mdulo Descriptor, seus elementos-filhos e seus atributos devem obrigatoriamente estar de acordo com a Tabela 21. Tabela 21 Mdulo Descriptor estendido Elementos
descriptor
Atributos
id, player, explicitDur, region, freeze, moveLeft, moveRight, moveUp, moveDown, focusIndex, focusBorderColor, focusBorderWidth, focusBorderTransparency, focusSrc,focusSelSrc, selBorderColor, transIn, transOut name, value id
Contedo
(descriptorParam)*
descriptorParam descriptorBase
vazio (importBase|descriptor|descriptorSwitch)+
7.2.7
A rea funcional Linking define o mdulo Linking, responsvel por definir os elos, que utilizam conectores. Um elemento <link> pode ter um atributo id, que identifica univocamente o elemento dentro de um documento e deve obrigatoriamente ter um atributo xconnector, que refere-se ao URI de um conector hipermdia. A referncia deve obrigatoriamente ter o formato alias#connector_id, ou documentURI_value#connector_id, para conectores definidos em um documento externo (ver 7.2.11), ou simplesmente connector_id, para conectores definidos no prprio documento. O elemento <link> contm elementos-filhos chamados <bind>, que permitem associar ns a papis (roles) do conector (ver 7.2.8). Para fazer esta associao, um elemento <bind> tem quatro atributos bsicos. O primeiro chamado role, que usado para fazer referncia a um papel do conector. O segundo chamado component, que usado para identificar o n. O terceiro um atributo opcional chamado interface, usado para fazer referncia a uma interface do n. O quarto um atributo opcional chamado descriptor, usado para fazer referncia a um descritor a ser associado com o n, conforme definido pelo mdulo Descriptor (ver 7.2.6).
NOTA O atributo interface pode referir-se a qualquer interface do n, isto , uma ncora, uma propriedade ou uma porta, se for um n de composio. O atributo interface opcional. Quando no especificado, a associao feita com todo o contedo do n (ver 7.2.5).
Se o elemento conector definir parmetros (ver 7.2.8), convm aos elementos <bind> ou <link> definirem valores para esses parmetros, atravs de seus elementos-filhos chamados <bindParam> e <linkParam>, respectivamente, ambos com atributos name e value. Nesse caso, o atributo name deve obrigatoriamente fazer referncia ao nome de um parmetro do conector, enquanto o atributo value deve obrigatoriamente definir um valor a ser atribudo ao respectivo parmetro.
47
Os elementos do mdulo Linking, seus atributos e seus elementos-filhos devem obrigatoriamente estar de acordo com a Tabela 22. Tabela 22 Mdulo Linking estendido Elementos
bind bindParam linkParam link
Atributos
role, component, interface, descriptor name, value name, value id, xconnector (bindParam)* vazio vazio
Contedo
(linkParam*, bind+)
7.2.8
A rea funcional Connectors da NCL 3.0 particionada em sete mdulos bsicos: ConnectorCommonPart, ConnectorAssessmentExpression, ConnectorCausalExpression, CausalConnector, ConstraintConnector (no considerado nesta Norma), ConnectorBase e CompositeConnector (tambm no considerado nesta Norma). Os mdulos da rea funcional Connectors so totalmente independentes dos outros mdulos NCL. Esses mdulos formam o ncleo de uma linguagem nova de aplicao XML (de fato, outros perfis NCL 3.0) para a definio de conectores, que podem ser utilizados para especificar relaes de sincronizao espao-temporais, tratando relaes de referncia (de interao com usurio) como um caso particular de relaes de sincronizao temporal. Alm dos mdulos bsicos, a rea funcional Connectors tambm define mdulos que agrupam conjuntos de mdulos bsicos, para facilitar a definio do perfil de linguagem. Esse o caso do mdulo CausalConnectorFunctionality, utilizado na definio dos perfis EDTV, BDTV e CausalConnector. O mdulo CausalConnectorFunctionality agrupa os seguintes mdulos: ConnectorCommonPart, ConnectorAssessmentExpression, ConnectorCausalExpression e CausalConnector. Um elemento <causalConnector> representa uma relao causal que pode ser utilizada por elementos <link> em documentos. Em uma relao causal, uma condio deve obrigatoriamente ser satisfeita para disparar uma ao. Um <causalConnector> especifica uma relao independentemente dos relacionamentos, isto , ele no especifica quais ns (representados por elementos <media>, <context>, <body> e <switch>) interagirem atravs da relao. Um elemento <link>, por sua vez, representa um relacionamento, do tipo definido por seu conector, interligando diferentes ns. Os elos representando o mesmo tipo de relao, mas interligando diferentes ns, podem reutilizar o mesmo conector, reutilizando todas as especificaes. Um <causalConnector> especifica, atravs de seus elementos-filhos, um conjunto de pontos da interface, chamados papis. Um elemento <link> refere-se a um <causalConnector> e define um conjunto de mapeamentos (elementos <bind> filhos do elemento <link>), que associam cada extremidade do elo (interface de n) a um papel do conector utilizado. As relaes em NCL so baseadas em eventos. Um evento uma ocorrncia no tempo que pode ser instantnea ou ter durao mensurvel. A NCL 3.0 define os seguintes tipos de eventos: evento de apresentao, que definido pela apresentao de um subconjunto das unidades de informao de um objeto de mdia, especificado na NCL pelo elemento <area>, ou pelo n de mdia em si (apresentao de todo o contedo). Os eventos de apresentao tambm podem ser definidos sobre ns de composio (representados por um elemento <body>, <context> ou <switch>, representando a apresentao das unidades de informao de qualquer n dentro do n de composio); evento de seleo, que definido pela seleo de um subconjunto das unidades de informao de um objeto de mdia, especificado na NCL pelo elemento <area>, ou pelo prprio n de mdia (apresentao do contedo total);
48
evento de atribuio, que definido pela atribuio de um valor a uma propriedade de um n (representado por um elemento <media>, <body>, <context> ou <switch>), que deve obrigatoriamente ser declarado em um elemento <property>, filho do n; e evento de composio, que definido pela apresentao da estrutura de um n de composio (representado por um elemento <body>, <context> ou <switch>). Os eventos de composio so utilizados para apresentar o mapa da composio (organizao da composio). Cada evento define uma mquina de estados que recomenda-se que seja controlada pelo formatador NCL, como demonstrado na Figura 3. Alm disso, todo evento tem um atributo associado, denominado occurrences, que conta quantas vezes o evento vai do estado ocorrendo (occurring) ao estado preparado (sleeping), durante a apresentao de um documento. Eventos como apresentao e atribuio tambm tm um atributo denominado repetitions, que conta quantas vezes o evento deve obrigatoriamente ser reiniciado (transitou do estado ocorrendo para o preparado) pelo formatador. Esse atributo pode conter o valor indefinite, levando a uma repetio infinita (loop) das ocorrncias do evento at que ocorra alguma interrupo externa. Os nomes de transio para a mquina de estado de evento devem obrigatoriamente estar de acordo com a Tabela 23.
paused
stop | abort pause start resume
sleeping
occurring
Figura 3 Mquina de estado de evento Tabela 23 Nomes das transies para uma mquina de estado de evento Transio (causada por ao) sleeping occurring (start) occurring sleeping (stop or natural end) occurring sleeping (abort) occurring paused (pause) paused occurring (resume) paused sleeping (stop) paused sleeping (abort) Nome da transio starts stops aborts pauses resumes stops aborts
Um evento de apresentao associado com um n de mdia, representado por um elemento <media>, inicia no estado preparado. No incio da exibio de suas unidades de informao, o evento vai para o estado ocorrendo. Se a exibio for temporariamente suspensa, o evento permanece no estado pausado (paused), enquanto durar essa situao. Um evento de apresentao pode mudar de ocorrendo para preparado como conseqncia do trmino natural da durao da apresentao, ou devido a uma ao que termina o evento. Em ambos os casos, o atributo occurrences incrementado, e o atributo repetitions diminudo de um. Se, aps diminudo, o valor do atributo repetitions for maior que zero, o evento automaticamente reiniciado (volta novamente para o estado ocorrendo).
49
Quando a apresentao de um evento interrompida bruscamente, atravs de um comando para abortar a apresentao, o evento tambm vai para o estado preparado, mas sem incrementar o atributo occurrences e atualizando o valor do atributo repetitions para zero. A durao de um evento o tempo que ele permanece no estado ocorrendo. Tal durao pode ser intrnseca ao objeto de mdia, explicitamente especificada por um autor (atributo explicitDur de um elemento <descriptor>), ou derivado de um relacionamento. Um evento de apresentao associado com um n de composio representado por um elemento <body> ou <context> permanece no estado ocorrendo enquanto pelo menos um evento de apresentao associado com qualquer um dos ns filhos dessa composio estiver no estado ocorrendo, ou enquanto pelo menos um elo-filho do n de composio estiver sendo avaliado. Um evento de apresentao associado com um n de composio representado por um elemento <body> ou <context> est no estado pausado se pelo menos um evento de apresentao associado com qualquer um dos ns filhos da composio estiver no estado pausado e todos os outros eventos de apresentao associados com os ns filhos da composio estiverem no estado preparado ou pausado. Do contrrio, o evento de apresentao est no estado preparado.
NOTA Outros detalhes sobre o comportamento das mquinas de estado de evento de apresentao para ns de mdia e de composio so fornecidos na Seo 8.
Um evento de apresentao associado com um n switch, representado por um elemento <switch>, permanece no estado ocorrendo enquanto o elemento-filho do switch, escolhido (n selecionado) atravs das regras de ligao (bind rules), estiver no estado ocorrendo. Ele est no estado pausado se o n selecionado estiver no estado pausado. Do contrrio, o evento de apresentao est no estado preparado. Um evento de seleo iniciado no estado preparado. Ele permanece no estado ocorrendo enquanto a ncora correspondente (subconjunto das unidades de informao do objeto de mdia) estiver sendo selecionada. Os eventos de atribuio permanecem no estado ocorrendo enquanto os valores de propriedade correspondentes estiverem sendo modificados. Obviamente, eventos instantneos, como eventos para simples atribuio de valor, permanecem no estado ocorrendo apenas durante um perodo infinitesimal de tempo. Um evento de composio (associado a um n de composio representado por um elemento <body>, <context> ou <switch>) permanece no estado ocorrendo enquanto o mapa da composio estiver sendo apresentado. As relaes so definidas com base nos estados dos eventos, nas alteraes sobre as mquinas de estado de evento, sobre os valores de atributos dos eventos e sobre os valores de propriedade dos ns (elemento <media>, <body>, <context> ou <switch>). O mdulo CausalConnectorFunctionality permite apenas a definio de relaes causais, definidas pelo elemento <causalConnector> do mdulo CausalConnector. Um elemento <causalConnector> tem uma expresso de cola (glue expression), que define uma expresso de condio e uma de ao. Quando a expresso de condio satisfeita, a expresso de ao deve obrigatoriamente ser executada. O elemento <causalConnector> deve obrigatoriamente ter um atributo id, que identifica unicamente o elemento dentro de um documento. Uma expresso de condio pode ser simples (elemento <simpleCondition>) ou composta (elemento <compoundCondition>), ambos elementos definidos pelo mdulo ConnectorCausalExpression. O elemento <simpleCondition> tem um atributo role, cujo valor deve obrigatoriamente ser nico no conjunto de roles do conector. Um role (papel) um ponto de interface do conector, que pode ser associado a interfaces de ns por um elo que referencia o conector. Um elemento <simpleCondition> tambm define um tipo de evento (atributo eventType) e qual transio a condio se refere (atributo transition). Os atributos eventType e transition so opcionais. Eles podem ser inferidos pelo valor do atributo role se forem utilizados valores reservados. Do contrrio, atributos eventType e transition so obrigatrios.
50
Os valores reservados utilizados para definir os roles em <simpleCondition> so estabelecidos na Tabela 24. Se um valor de eventType for selection, o role pode tambm definir sobre qual dispositivo a seleo se refere (por exemplo, teclas de um teclado ou controle remoto), atravs do seu atributo key. Pelo menos os seguintes valores (que so sensveis ao tipo maiscula ou minscula) devem obrigatoriamente ser aceitos pelo atributo key: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z, *, #, MENU, INFO, GUIDE, CURSOR_DOWN, CURSOR_LEFT, CURSOR_RIGHT, CURSOR_UP, CHANNEL_DOWN, CHANNEL_UP, VOLUME_DOWN, VOLUME_UP, , ENTER, RED, GREEN, YELLOW, BLUE, BACK, EXIT, POWER, REWIND, STOP, EJECT, PLAY, RECORD, PAUSE. Tabela 24 Valores reservados para especificao da condio do role associados s mquinas de estado de evento
Valor de role Valor da transio Tipo de evento
A cardinalidade do role especifica o nmero mnimo (atributo min) e mximo (atributo max) dos participantes que podem exercer o papel (nmero de binds) quando o <causalConnector> utilizado para criar um <link>. O valor mnimo da cardinalidade deve obrigatoriamente ser sempre um valor finito positivo, maior que zero e menor ou igual ao valor mximo da cardinalidade. Se a cardinalidade mnima e a mxima no forem informadas, 1 deve obrigatoriamente ser assumido como valor (default) para ambos os parmetros. Quando o valor mximo de cardinalidade for maior que um, vrios participantes podem executar o mesmo papel (role), isto , pode haver vrias ligaes (binds) conectando diversos ns ao mesmo papel. O valor unbounded pode ser dado ao atributo max, se o role puder ter binds ilimitados associados a ele. Nos dois ltimos casos, convm que um atributo qualifier seja especificado para informar a relao lgica entre os binds de condio simples. Como descrito na Tabela 25, os valores possveis para o atributo qualifier so: or (ou) ou and (e). Se o qualificador (atributo qualifier) estabelecer um operador lgico or, o elo ser acionado quando da ocorrncia de qualquer condio. Se o qualificador estabelecer um operador lgico and, o elo ser acionado aps a ocorrncia de todas as condies simples. Se no especificado, deve-se obrigatoriamente assumir o valor (default) or. Tabela 25 Valores do qualificador para condies simples
Elemento role <simpleCondition> <simpleCondition> Qualificador or and Semntica
Verdadeiro sempre que ocorre qualquer condio simples associada Verdadeiro imediatamente aps a ocorrncia de todas as condies simples associadas
Um atributo de retardo (delay) pode tambm ser definido para uma <simpleCondition>, especificando que a condio verdadeira aps um perodo de retardo a partir do momento em que a transio ocorre.
51
O elemento <compoundCondition> tem um atributo operator com o valor Booleano (and ou or), relacionando seus elementos-filhos: <simpleCondition>, <compoundCondition>, <assessmentStatement> e <compoundStatement>. Um atributo delay pode tambm ser definido, especificando que a condio composta verdadeira depois que um tempo de retardo do momento em que a expresso, relacionada a seus elementosfilhos, for verdadeira. Os elementos <assessmentStatement> e <compoundStatement> so definidos pelo mdulo ConnectorAssessmentExpression.
NOTA Quando uma condio and composta relaciona-se a mais de uma condio de disparo (isto , uma condio somente satisfeita em um instante de tempo infinitesimal como, por exemplo, o final da apresentao de um objeto), a condio composta deve obrigatoriamente ser considerada verdadeira no instante imediatamente aps a satisfao de todas as condies de disparo.
Uma expresso de ao capta aes que podem ser executadas em relaes causais, podendo ser compostas de um elemento <simpleAction> ou <compoundAction>, tambm definido pelo mdulo ConnectorCausalExpression. O elemento <simpleAction> tem um atributo role, que deve obrigatoriamente ser nico no conjunto de papis (roles) do conector. Como sempre, um papel um ponto de interface do conector, que est associado s interfaces de ns por um <link> que se refere ao conector. Um elemento <simpleAction> tambm define um tipo de evento (atributo eventType) e qual transio de estado de evento ele dispara (actionType). Os atributos eventType e actionType so opcionais. Eles podem ser inferidos pelo valor de role, se forem utilizados valores reservados. Do contrrio, atributos eventType e actionType so obrigatrios. Os valores reservados utilizados para definir os roles de um elemento <simpleAction> so estabelecidos na Tabela 26. Tabela 26 Valores de role de ao reservados associados s mquinas de estado de evento Role value start stop abort pause resume set start stop abort pause resume start Action type Event type presentation presentation presentation presentation presentation attribution
Se um valor eventType for attribution, o elemento <simpleAction> tambm deve obrigatoriamente definir o valor a ser atribudo, atravs de seu atributo value. Se esse valor for especificado como $anyName (onde o $ smbolo reservado e anyName qualquer cadeia de caracteres, exceto um dos nomes reservados para papis), o valor a ser atribudo deve ser obtido da propriedade ligada role=anyName, definida em um elemento <bind> do elemento <link> que utiliza o conector. Se esse valor no puder ser obtido, nenhuma atribuio deve ser realizada.
NOTA 1 Declarar o atributo role=anyName num elemento <bind> de um <link>, implica em ter um papel implicitamente declarado como: <attributeAssessment role=anyName eventType=attribution attributeType=nodeProperty/>. Esse o nico caso possvel de um elemento <bind> se referenciar a um papel no definido explicitamente em um conector. NOTA 2 No caso de value=$anyName, o valor a ser atribudo deve obrigatoriamente ser o valor de uma propriedade (elemento <property>) de um componente da mesma composio onde o elo (elemento <link>) que referencia o evento definido, ou uma propriedade da composio onde o elo definido, ou uma propriedade de um elemento acessvel atravs de uma porta da composio onde o elo definido, ou ainda uma propriedade de um elemento acessvel atravs de uma porta de uma composio (elementos <port> ou <switchPort>) aninhada na mesma composio onde o elo definido.
Como no caso dos elementos <simpleCondition>, a cardinalidade do role especifica o nmero mnimo (atributo min) e mximo (atributo max) dos participantes de um role (nmero de binds), quando o <causalConnector> utilizado para criar um elo. Quando o valor mximo da cardinalidade maior que um, vrios participantes podem participar de um mesmo role. Quando tem valor unbounded, o nmero de binds ilimitado. Nos ltimos dois casos, um qualificador deve obrigatoriamente ser especificado. A Tabela 27 apresenta os possveis valores de qualificador.
52
Um atributo delay pode tambm ser definido por um <simpleAction>, especificando, quando definido, que a ao deve obrigatoriamente ser disparada apenas aps esperar pelo tempo especificado. Alm disso, o <simpleAction> tambm pode definir um atributo repeat para ser aplicado ao atributo repetitions do evento, e um atributo repeatDelay, para ser aguardado antes da repetio da ao. Alm de todos os atributos acima citados, o elemento <simpleAction> tambm pode ter atributos definidos na rea funcional Animation (atributos duration e by), se seu valor de eventType for attribution (ver 7.2.13). O elemento <compoundAction> tem um atributo operator (par ou seq) relacionando seus elementos-filhos: <simpleAction> e <compoundAction>. Aes compostas paralelas ("par") e seqenciais ("seq") especificam que a execuo das aes deve obrigatoriamente ser feita em qualquer ordem ou em uma ordem especfica, respectivamente. Um atributo de delay pode tambm ser definido, especificando que a ao composta deve obrigatoriamente ser aplicada aps o retardo especificado. Quando o operador seqencial utilizado, as aes devem obrigatoriamente ser iniciadas na ordem especificada. Entretanto, uma ao no precisa esperar at que a anterior seja completada para ento ser iniciada. O mdulo ConnectorAssessmentExpression define quatro <attributeAssessment>, <valueAssessment> e <compoundStatement>. elementos: <assessmentStatement>,
O <attributeAssessment> tem um atributo role, que deve obrigatoriamente ser nico no conjunto de roles do conector. Como normalmente ocorre, um role um ponto de interface do conector, que associado s interfaces dos ns por um <link> que referencia o conector. Um <attributeAssessment> tambm define um tipo de evento (atributo eventType). Se o valor de eventType for selection (seleo), convm ao <attributeAssessment> tambm definir sobre qual equipamento a seleo se refere (por exemplo, teclas de um teclado ou controle remoto), atravs do seu atributo key. Se o valor eventType for presentation, o atributo attributeType especifica o atributo de evento (occurrences ou repetitions) ou o estado do evento (state); se o valor eventType for selection, o atributo attributeType opcional e, se presente, pode ter o valor occurrences (default) ou state; se o eventType for attribution o attributeType opcional e pode ter o valor nodeProperty (default), occurrences, repetition ou state. No primeiro caso, o evento representa uma propriedade do n a ser avaliada, nos outros, o evento representa a avaliao da propriedade de evento de atribuio correspondente ou o estado do evento de atribuio. Um valor de compensao (offset) pode ser adicionado a um <attributeAssessment> antes da comparao (por exemplo, uma compensao pode ser adicionada a uma avaliao de atributo para especificar: a posio vertical da tela mais 50 pixels. O elemento <valueAssessment> tem um atributo value que deve obrigatoriamente assumir um valor de estado de evento, ou qualquer valor a ser comparado com uma propriedade do n ou atributo de evento. O elemento <assessmentStatement> tem um atributo comparator que compara os valores inferidos a partir dos seus elementos-filhos (elementos <attributeAssessment> e <valueAssessment>): a) no caso de <attributeAssessment>: um valor de propriedade do n [eventType = attribution e o attributeType = nodeProperty]; ou um valor de atributo de evento [eventType = (presentation, attribution ou selection) e o attributeType = (occurrences ou repetition)]; ou um estado de evento [eventType = (presentation, attribution ou selection) e o attributeType = state]; no caso do <valueAssessment>: um valor de seu atributo value.
b)
53
O elemento <compoundStatement> tem um atributo operator com um valor Booleano (and ou or) relacionando seus elementos-filhos: <assessmentStatement> ou <compoundStatement>. Um atributo isNegated tambm pode ser definido para especificar se o elemento-filho do <compoundStatement> deve obrigatoriamente ser negado antes que a operao Booleana seja avaliada. O elemento <causalConnector> pode ter elementos-filhos (elementos <connectorParam>), que so utilizados para parametrizar valores dos atributos dos conectores. O mdulo ConnectorCommonPart define o tipo de elemento <connectorParam>, que tem atributos name e type. Para especificar quais atributos recebem valores de parmetro definidos pelo conector, seus valores so especificados como o nome do parmetro, precedido pelo smbolo $.
EXEMPLO Para parametrizar o atributo delay, um parmetro chamado actionDelay definido (<connectorParam name="actionDelay" type=unsignedLong/>) e o valor $actionDelay utilizado no atributo (delay=$actionDelay).
Os elementos do mdulo CausalConnectorFunctionality, seus elementos-filhos e seus atributos devem obrigatoriamente estar de acordo com a Tabela 28. Tabela 28 Mdulo CausalConnectorFunctionality estendido Elementos
causalConnector connectorParam simpleCondition id name, type role, delay, eventType, key, transition, min, max, qualifier operator, delay role, delay, eventType, actionType, value, min, max, qualifier, repeat, repeatDelay, duration, by operator, delay comparator
Atributos
Contedo
(connectorParam*, (simpleCondition | compoundCondition), (simpleAction | compoundAction)) vazio vazio ((simpleCondition | compoundCondition)+, (assessmentStatement | compoundStatement)*) vazio (simpleAction | compoundAction)+ (attributeAssessment, (attributeAssessment | valueAssessment))
compoundCondition
attributeAssessment
valueAssessment compoundStatement
vazio
vazio (assessmentStatement | compoundStatement)+
O mdulo ConnectorBase define um elemento chamado <connectorBase>, que permite o agrupamento de conectores. Como normalmente ocorre, recomenda-se que o elemento <connectorBase> tenha um atributo id, que identifica unicamente o elemento dentro de um documento. O contedo exato de uma base de conectores especificado por um perfil de linguagem que utiliza as facilidades oferecidas pelos conectores. Entretanto, como a definio de conectores no facilmente realizada por usurios inexperientes, a idia ter usurios experientes definindo os conectores, armazenando-os em bibliotecas (bases de connectores) que possam ser importadas, tornando-as disponveis a outros usurios para a criao de elos. O Anexo C fornece um exemplo de definies de conectores que podem ser importadas.
54
Os elementos do mdulo ConnectorBase, seus elementos-filhos e seus atributos devem obrigatoriamente estar de acordo com a Tabela 29. Tabela 29 Mdulo ConnectorBase estendido Elementos
connectorBase id
Atributos
Contedo
(importBase|causalConnector)*
7.2.9
O objetivo da rea funcional Presentation Control especificar alternativas de contedo e apresentao para um documento. Essa rea functional particionada em quatro mdulos, chamados TestRule, TestRuleUse, ContentControl e DescriptorControl. O mdulo TestRule permite a definio de regras que, quando satisfeitas, selecionam alternativas para a apresentao do documento. A especificao de regras em NCL 3.0 feita em um mdulo separado, porque so teis para definir tanto componentes quanto descritores alternativos. O elemento <ruleBase> especifica um conjunto de regras e deve obrigatoriamente ser definido como elementofilho do elemento <head>. Essas regras podem ser simples, definidas pelo elemento <rule>, ou compostas, definidas pelo elemento <compositeRule>. As regras simples definem um identificador (atributo id), uma varivel (atributo var), um valor (atributo value) e um comparador (atributo comparator) relacionando a varivel a um valor. A varivel deve obrigatoriamente ser uma propriedade do n settings (elemento <media> do tipo application/x-ginga-settings), ou seja, o atributo var deve obrigatoriamente possuir o mesmo valor do atributo name de um elemento <property>, definido como filho do elemento <media> do tipo application/x-gingasettings. Regras compostas tm um identificador (atributo id) e um operador Booleano (and ou or atributo operator) relacionando suas regras-filhas. Como normalmente ocorre, o atributo id identifica unicamente os elementos <rule> e <compositeRule> dentro de um documento. Os elementos do mdulo TestRule, seus elementos-filhos e seus atributos devem obrigatoriamente estar de acordo com a Tabela 30. Tabela 30 Mdulo TestRule estendido Elementos
ruleBase Rule compositeRule id id, var, comparator, value id, operator
Atributos
Contedo
(importBase|rule|compositeRule)+ vazio (rule | compositeRule)+
O TestRuleUse define o elemento <bindRule>, que utilizado para associar regras com componentes de um elemento <switch> ou <descriptorSwitch>, atravs de seus atributos rule e constituent, respectivamente. O elemento do mdulo TestRuleUse e seus atributos devem obrigatoriamente estar de acordo com a Tabela 31. Tabela 31 Mdulo TestRuleUse estendido Elementos
bindRule
Atributos
constituent, rule vazio
Contedo
55
O mdulo ContentControl especifica o elemento <switch>, permitindo a definio de ns alternativos a serem escolhidos em tempo de apresentao do documento. As regras de teste utilizadas para escolher o componente do switch a ser apresentado so definidas pelo mdulo TestRule, ou so regras de teste especificamente definidas e embutidas em uma implementao do formatador NCL. O mdulo ContentControl tambm define o elemento <defaultComponent>, cujo atributo component (do tipo IDREF) identifica o elemento (default) que deve obrigatoriamente ser selecionado se nenhuma das regras bindRule for avaliada como verdadeira. Para permitir a definio de elos que se ligam a ncoras do componente escolhido depois da avaliao das regras de um switch, recomenda-se que um perfil da linguagem tambm inclua o mdulo SwitchInterface, que permite a definio de interfaces especiais, chamadas <switchPort>. Os elementos <switch> devem obrigatoriamente ter um atributo id, que identifica unicamente o elemento dentro de um documento. O atributo refer uma extenso definida no mdulo Reuse (ver 7.2.11). Quando um <context> definido como elemento-filho de um <switch>, os elementos <link> recursivamente contidos no elemento <context> devem obrigatoriamente ser considerados por um exibidor NCL apenas se <context> for selecionado aps a avaliao do switch. Caso contrrio, recomenda-se que os elementos <link> sejam considerados desabilitados e obrigatoriamente no devem interferir na apresentao do documento. Os elementos do mdulo ContentControl, seus elementos-filhos e seus atributos devem obrigatoriamente estar de acordo com a Tabela 32. Tabela 32 Mdulo ContentControl estendido Elementos
switch defaultComponent
Atributos
id, refer component
Contedo
defaultComponent?, (switchPort | bindRule | media | context | switch)*) vazio
O mdulo DescriptorControl especifica o elemento <descriptorSwitch>, que contm um conjunto de descritores alternativos a ser associado a um objeto. Os elementos <descriptorSwitch> devem obrigatoriamente ter um atributo id, que identifica unicamente o elemento dentro de um documento. Analogamente ao elemento <switch>, a escolha <descriptorSwitch> feita em tempo de apresentao, utilizando regras de teste definidas pelo mdulo TestRule, ou regras de teste especificamente definidas e embutidas em uma implementao do formatador NCL. O mdulo DescriptorControl tambm define o elemento <defaultDescriptor>, cujo atributo descriptor (do tipo IDREF) identifica o elemento (default) que deve obrigatoriamente ser selecionado se nenhuma das regras bindRule for avaliada como verdadeira. Os elementos do mdulo DescriptorControl, seus elementos-filhos e seus atributos devem obrigatoriamente estar de acordo com a Tabela 33. Tabela 33 Mdulo DescriptorControl estendido Elementos
descriptorSwitch defaultDescriptor id descriptor
Atributos
vazio
Contedo
(defaultDescriptor?, (bindRule | descriptor)*)
Durante a apresentao de um documento, a partir do momento em que um <switch> avaliado, ele considerado resolvido at o final de sua apresentao, ou seja, enquanto seu evento de apresentao correspondente est no estado ocorrendo ou pausado. Durante a apresentao de um documento, a partir do momento em que um <descriptorSwitch> avaliado, ele considerado resolvido at o final da apresentao do elemento <media> que lhe foi associado, ou seja, enquanto qualquer evento de apresentao associado com o elemento <media> estiver no estado ocorrendo ou pausado.
56
NOTA Recomenda-se que os formatadores NCL posterguem a avaliao do switch at o momento que um elo ancorado ao switch precisar ser avaliado. Convm que a avaliao do descriptorSwitch seja atrasada at o momento em que o objeto referindo-se a ele precise estar preparado para ser apresentado.
7.2.10 rea funcional Timing A rea funcional Timing define o mdulo Timing. O mdulo Timing permite a definio de atributos temporais para componentes de um documento. Basicamente, esse mdulo define atributos para especificar o que acontece com um objeto ao final de sua apresentao (freeze) e a durao ideal de um objeto (explicitDur). Esses atributos podem ser incorporados pelos elementos <descriptor>. 7.2.11 rea funcional Reuse NCL permite uma grande reutilizao de seus elementos. A rea funcional Reuse da NCL particionada em trs mdulos: Import, EntityReuse e ExtendedEntityReuse. Para permitir que uma base de entidades seja incorporada a outra base j existente, o mdulo Import define o elemento <importBase>, que tem dois atributos: documentURI e alias. O atributo documentURI refere-se a um URI correspondente ao documento NCL contendo a base a ser importada. O atributo alias especifica um nome a ser utilizado como prefixo quando for necessrio referir-se a elementos dessa base importada. O nome do atributo alias deve obrigatoriamente ser nico em um documento e seu escopo restrito ao documento que o definiu. A referncia teria o formato: alias#element_id. A operao de importao transitiva, ou seja, se a baseA importa a baseB que importa a baseC, ento a baseA importa a baseC. Entretanto, o alias definido para a baseC dentro da baseB obrigatoriamente no deve ser considerado pela baseA. Quando um perfil de linguagem utiliza o mdulo Import, as seguintes especificaes so permitidas: o elemento <descriptorBase> pode ter um elemento-filho <importBase> referindo-se a um URI correspondente a um outro documento NCL contendo a base de descritores a ser importada (na verdade seus elementos-filhos) e aninhada. Quando uma base de descritores importada, a base de regies e a base de regras, quando existentes no documento importado, so tambm automaticamente importadas para as bases de regies e de regras do documento correspondente que realiza a importao; o elemento <connectorBase> pode ter um elemento-filho <importBase> referindo-se a um URI correspondente a uma outra base de conectores a ser importada (na verdade seus elementos-filhos) e aninhada; o elemento <transitionBase> pode ter um elemento-filho <importBase> referindo-se a um URI correspondente a uma outra base de transies a ser importada (na verdade seus elementos-filhos) e aninhada; o elemento <regionBase> pode ter um elemento-filho <importBase> referindo-se a um URI correspondente a um outro documento NCL contendo a base da regies a ser importada (na verdade seus elementos-filhos) e aninhada. Embora NCL defina seu modelo de leiaute, nada impede que um documento NCL utilize outros modelos de leiaute, desde que eles definam regies onde os objetos podem ser apresentados, como, por exemplo, modelos de leiaute SMIL 2.1. Ao importar uma <regionBase>, um atributo opcional denominado region pode ser especificado, dentro de um elemento <importBase>. Quando presente, o atributo deve obrigatoriamente identificar o id de um elemento <region> declarado no elemento <regionBase> do documento hospedeiro (documento que fez a operao de importao). Como conseqncia, todos os elementos <region>, filhos do <regionBase> importados, devem obrigatoriamente ser considerados elementos <region> filhos da regio referida pelo atributo region do <importBase>. Se no especificado, os elementos <region>, filhos do <regionBase> importado, devem obrigatoriamente ser considerados filhos diretos do elemento <regionBase> do documento hospedeiro. O elemento <importedDocumentBase> especifica um conjunto de documentos NCL importados e deve obrigatoriamente ser definido como elemento-filho do elemento <head>. O elemento <importedDocumentBase> deve obrigatoriamente ter um atributo id, que identifica unicamente o elemento dentro de um documento.
57
Um documento NCL pode ser importado atravs de um elemento <importNCL>. Todas as bases definidas dentro de um documento NCL, bem como o elemento <body> do documento, so importados todos de uma vez, atravs do elemento <importNCL>. As bases so tratadas como se cada uma tivesse sido importada por um elemento <importBase>. O elemento <body> importado ser tratado como um elemento <context>. O elemento <importNCL> no inclui o documento NCL referido, mas apenas torna o documento referenciado visvel para que os seus componentes possam ser reusados pelo documento que definiu o elemento <importNCL>. Assim, o <body> importado, bem como quaisquer de seus ns, pode ser reusado dentro do elemento <body> do documento NCL que realizou a importao. O elemento <importNCL> tem dois atributos: documentURI e alias. O documentURI refere-se a um URI correspondente ao documento a ser importado. O atributo alias especifica um nome a ser utilizado quando for realizada uma referncia a elementos desse documento importado. Como no elemento <importBase>, o nome deve obrigatoriamente ser nico (type=ID) e seu escopo restrito ao documento que definiu o atributo alias. A referncia teria o formato: alias#element_id. importante notar que o mesmo alias convm ser utilizado quando necessrio referir-se a elementos definidos nas bases do documento importado (<regionBase>, <connectorBase>, <descriptorBase> etc). A operao do elemento <importNCL> tambm tem propriedade transitiva, ou seja, se o documentoA importar o documentoB que importa documentoC, ento o documentoA importa o documentoC. Entretanto, o alias definido para o documentoC dentro do documentoB obrigatoriamente no deve ser considerado pelo documentoA. Os elementos do mdulo Import, seus elementos-filhos e seus atributos devem obrigatoriamente estar de acordo com a Tabela 34. Tabela 34 Mdulo Import estendido Elementos importBase importedDocumentBase importNCL id alias, documentURI Atributos alias, documentURI, region vazio (importNCL)+ vazio Contedo
O mdulo EntityReuse permite que um elemento NCL seja reusado. Esse mdulo define o atributo refer, que referencia um elemento id que ser reusado. Apenas <media>, <context>, <body> e <switch> podem ser reusados. Um elemento que referencia um outro elemento no pode ser reusado; isto , seu id no pode ser o valor de um atributo refer. Se o n referenciado for definido dentro de um documento D importado, o valor do atributo refer deve obrigatoriamente ter o formato alias#id, onde alias o valor do atributo alias associado ao documento D importado. Quando um perfil da linguagem utiliza o mdulo EntityReuse, ele pode adicionar o atributo refer a: um elemento <media> ou <switch>. Nesse caso, o elemento referenciado deve obrigatoriamente ser, respectivamente, um elemento <media> ou <switch>, que representa o mesmo n previamente definido no prprio <body> do documento ou em um <body> externo importado. O elemento referenciado deve obrigatoriamente conter diretamente a definio de todos os seus atributos e elementos-filhos; um elemento <context>. Nesse caso, o elemento referenciado deve obrigatoriamente ser um elemento <context> ou <body>, que representa o mesmo contexto previamente definido no <body> do prprio documento ou em um <body> externo importado. O elemento referenciado deve obrigatoriamente conter diretamente a definio de todos os seus atributos e elementos-filhos.
58
Quando um elemento declara um atributo refer, todos os atributos e elementos-filhos definidos pelo elemento referenciado so herdados. Todos os outros atributos e elementos-filhos, se definidos pelo elemento que realiza a referncia, devem obrigatoriamente ser ignorados pelo formatador, exceto o atributo id que deve obrigatoriamente ser definido. A nica outra exceo para elementos <media>, para os quais novos elementos-filhos <area> e <property> podem ser adicionados, e um novo atributo, instance, pode ser definido. Se o novo elemento <property> adicionado tiver o mesmo atributo name de um elemento <property> j existente (definido no elemento <media> reutilizado), o novo elemento <property> adicionado deve obrigatoriamente ser ignorado. Igualmente, se o novo elemento <area> adicionado tiver o mesmo atributo id de um elemento <area> j existente (definido no elemento <media> reutilizado), o novo elemento <area> adicionado deve obrigatoriamente ser ignorado. O atributo instance definido no mdulo ExtendedEntityReuse e tem new como seu valor default de string. O elemento referenciado e o elemento que o referencia devem obrigatoriamente ser considerados o mesmo, com relao s suas estruturas de dados. Em outras palavras, isso significa que um n NCM pode ser representado por mais que um elemento NCL. Como ns contidos em um n de composio NCM definem um conjunto, um n NCM pode ser representado por no mais que um elemento NCL dentro de uma composio. Isso significa que o atributo id de um elemento NCL representando um n NCM no apenas um identificador nico para o elemento, mas tambm o nico identificador correspondente ao n NCM na composio.
NOTA Pode-se consultar a NCMCore:2005 para outras informaes.
EXEMPLO Supondo que o elemento NCL (node1) representa um n NCM, os elementos NCL que o referenciam (node1ReuseA, node1ReuseB) representam o mesmo n NCM. Em outras palavras, o n NCM nico representado por mais de um elemento NCL (node1, node1ReuseA, e node1ReuseB). Mais ainda, como os ns contidos em um n de composio NCM definem um conjunto, cada um dos elementos NCL, node1, node1ReuseA e node1ReuseB, deve ser declarado dentro de uma composio diferente.
O elemento referenciado e o elemento que o referencia tambm devem obrigatoriamente ser considerados o mesmo n em relao sua estrutura de apresentao, se o atributo instance receber um valor instSame ou gradSame. Portanto, a seguinte semntica deve obrigatoriamente ser respeitada. Considere o conjunto de elementos <media> composto pelo elemento <media> referenciado e todos os elementos <media> que o referenciam. Se qualquer elemento do subconjunto formado pelo elemento <media> referenciado e todos os outros elementos <media> que tm o atributo instance igual a instSame ou gradSameestiver agendado para ser apresentado, todos os outros elementos nesse subconjunto, que no so descendentes de um elemento <switch>, esto tambm agendados para apresentao e, mais que isso, quando eles forem apresentados, devem obrigatoriamente ser representados pela mesma instncia de apresentao. Elementos descendentes de um elemento <switch> tambm devem obrigatoriamente ter o mesmo comportamento, se todas as regras necessrias para apresent-los forem satisfeitas; caso contrrio, eles no devem ser agendados para apresentao. Se o atributo instance for igual a instSame, todos os ns agendados do subconjunto devem ser apresentados obrigatoriamente em uma nica instncia, imediatamente (instruo start aplicada em todos os elementos do subconjunto simultaneamente). Se o atributo instance for igual a gradSame, todos os ns agendados so apresentados em uma nica instncia, mas gradativamente, medida que vo sofrendo a instruo start, proveniente de elos etc. A instncia comum em apresentao deve obrigatoriamente notificar todos os eventos associados com os elementos <area> e <property> definidos em todos os elementos <media> do subconjunto que foram agendados para apresentao. Por outro lado, os elementos <media> no conjunto que tem valores de atributo instance iguais a new obrigatoriamente no devem ser agendados para apresentao. Quando so individualmente agendados para apresentao, nenhum outro elemento do conjunto tem seu comportamento afetado, e mais, novas instncias independentes de apresentao devem obrigatoriamente ser criadas a cada inicio individual de apresentao. 7.2.12 rea funcional Navigational Key A rea funcional Navigational Key define o mdulo KeyNavigation que oferece as extenses necessrias para descrever as operaes de movimentao do foco, definido por um dispositivo, como um controle remoto. Basicamente, o mdulo define atributos que podem ser incorporados por elementos <descriptor>.
59
O atributo focusIndex especifica um ndice para o elemento <media> sobre o qual o foco pode ser aplicado, quando esse elemento estiver em exibio, utilizando o elemento <descriptor> que definiu o atributo. Quando um elemento <descriptor> no definir esse atributo, ele considerado como se no pudesse receber o foco. Em um determinado momento da apresentao, se o foco no tiver sido ainda definido, ou se estiver perdido, um foco ser inicialmente aplicado ao elemento que estiver sendo apresentado cujo descritor tenha o menor valor de ndice. Os valores do atributo focusIndex devem obrigatoriamente ser nicos em um documento NCL. Caso contrrio, atributos repetidos devem obrigatoriamente ser ignorados, se em um dado momento houver mais de um elemento <media> a ganhar o foco. Alm disso, quando um elemento <media> referencia um outro elemento <media> (utilizando o atributo refer especificado em 7.2.11), ele deve obrigatoriamente ignorar o focusIndex especificado pelo elemento <descriptor> associado ao elemento <media> referido. O atributo moveUp especifica um valor igual ao valor do focusIndex associado ao elemento sobre o qual o foco ser aplicado quando a tecla seta para cima (up arrow key) for pressionada. O atributo moveDown especifica um valor igual ao valor do focusIndex associado ao elemento sobre o qual o foco ser aplicado quando a tecla seta para baixo (down arrow key) for pressionada. O atributo moveRight especifica um valor igual ao valor do focusIndex associado ao elemento sobre o qual o foco ser aplicado quando a tecla seta para a direita (right arrow key) for pressionada. O atributo moveLeft especifica um valor igual ao valor do focusIndex associado ao elemento sobre o qual o foco ser aplicado quando a tecla seta para a esquerda (left arrow key) for pressionada. Quando o foco aplicado a um elemento com a propriedade de visibilidade com o valor false, ou a um elemento que no estiver sendo apresentado, o foco atual no deve se mover. O atributo focusSrc pode especificar um contedo alternativo a ser apresentado, ao invs do contedo da apresentao atual, se um elemento receber o foco. Esse atributo segue as mesmas regras do atributo src do elemento <media>. Quando um elemento recebe um foco, a moldura (box) definida pelos atributos de posicionamento do elemento deve obrigatoriamente ser destacada. O atributo focusBorderColor define a cor de destaque e pode receber os nomes reservados de cor: white, black, silver, gray, red, maroon, fuchsia, purple, lime, green, yellow, olive, blue, navy, aqua, ou teal. O atributo focusBorderWidth define a largura em pixels da borda em destaque (0 significa que nenhuma borda aparece, valores positivos significam que a borda est fora do contedo do objeto e valores negativos significam que a borda desenhada sobre o contedo do objeto); o atributo focusBorderTransparency define a transparncia da cor de destaque. O focusBorderTransparency deve obrigatoriamente ser um valor real entre 0 e 1, ou um valor real na faixa [0,100] terminando com o caractere % (por exemplo, 30 %), com 1 ou 100 % significando transparncia total e 0 ou 0 % significando nenhuma transparncia. Quando o focusBorderColor, o focusBorderWidth ou o focusBorderTransparency no esto definidos, valores default devem obrigatoriamente ser assumidos. Esses valores so especificados nas propriedades do elemento <media> do tipo application/x-ginga-settings: defaultFocusBorderColor, defaultFocusBorderWidth e defaultFocusTransparency, respectivamente. Quando um elemento em foco selecionado pressionando a tecla de ativao, o atributo focusSelSrc pode especificar um contedo de mdia alternativo a ser apresentado, ao invs da apresentao atual. Este atributo segue as mesmas regras do atributo src do elemento <media>. Quando selecionada, a caixa definida pelos atributos de posicionamento de elemento deve obrigatoriamente ser destacada com a cor definida pelo atributo selBorderColor (valor-default especificado pelo defaultSelBorderColor do elemento <media> do tipo application/xginga-settings), a largura da borda em destaque definida pelo atributo focusBorderWidth e a transparncia da cor da borda definida pelo atributo focusBorderTransparency. Quando um elemento em foco selecionado pressionando a tecla de ativao, o controle do foco deve obrigatoriamente ser passado ao exibidor do elemento <media> (player). O exibidor pode ento seguir suas prprias regras para navegao. O controle de foco deve obrigatoriamente ser devolvido ao formatador NCL quando a tecla back for pressionada. Nesse caso, o foco vai para o elemento identificado pelo atributo service.currentFocus do n settings (elemento <media> do tipo application/x-ginga-settings).
NOTA O controle do foco pode tambm ser passado alterando o valor do atributo service.currentKeyMaster do n settings (elemento <media> do tipo application/x-ginga-settings). Isto pode ser feito via ao de um elo (<link> element), via um comando executado por um cdigo imperativo de um n (objeto NCLua ou NCLet), ou pelo exibidor do n que detm o controle corrente.
60
7.2.13 rea funcional Animation Animao na verdade uma combinao de dois fatores: suporte ao desenho do objeto e suporte ao movimento do objeto ou, mais propriamente, suporte para a alterao do objeto em funo do tempo. NCL no um formato de contedo e, como tal, no tem suporte para a criao de objetos de mdia e no tem um mtodo generalizado para alterar o contedo do objeto de mdia. Ao contrrio, NCL um formato de escalonamento e orquestrao. Isso significa que NCL no pode ser utilizada para fazer desenhos animados, mas pode ser utilizada para exibir objetos de desenho animado no contexto de uma apresentao geral e para alterar as propriedades de sincronizao e exibio de um objeto de um desenho animado (ou qualquer outro) como um todo, enquanto o objeto estiver sendo exibido. As primitivas de animao NCL permitem que os valores de propriedades dos ns sejam alterados durante uma durao determinada. Como a animao NCL pode ser computacionalmente intensa, ela somente suportada pelo perfil EDTV e apenas as propriedades que definem valores numricos e cores podem ser animadas. A rea funcional Animation define o mdulo Animation que fornece as extenses necessrias para descrever o que acontece quando o valor de uma propriedade de um n alterado. Basicamente, o mdulo define atributos que podem ser incorporados pelos elementos <simpleAction> de um conector, se seu valor eventType for attribution. Dois novos atributos so definidos: duration e by. Ao atribuir um novo valor para uma propriedade, a alterao instantnea por default (duration=0), mas a alterao tambm pode ser feita durante um perodo explicitamente declarado, especificado pelo atributo duration. Alm disso, ao atribuir um novo valor a uma propriedade, a alterao do valor antigo para o novo pode ser linear por default (by=indefinite), ou feita passo a passo, com o passo especificado pelo atributo by. A combinao das definies dos atributos duration e by oferece a definio de como (de forma discreta ou linear) a alterao deve obrigatoriamente ser realizada e o seu intervalo de transformao. 7.2.14 rea funcional Transition Effects A rea funcional Transition Effects dividida em dois mdulos: TransitionBase e Transition.
NOTA Pode-se consultar o SMIL 2.1 Specification:2005 para outras informaes.
O mdulo TransitionBase definido pela NCL 3.0 e consiste em um elemento <transitionBase> que especifica um conjunto de efeitos de transio e deve obrigatoriamente ser definido como elemento-filho do elemento <head>. O elemento <transitionBase>, seus elementos-filhos e seus atributos devem obrigatoriamente estar de acordo com a Tabela 35. Tabela 35 Mdulo TransitionBase estendido Elementos transitionBase id Atributos Contedo (importBase, transition)+
O mdulo Transition baseado nas especificaes SMIL 2.1. O mdulo tem apenas um elemento chamado <transition>.
NOTA Pode-se consultar o SMIL 2.1 Specification, 2005 para outras informaes.
No perfil NCL 3.0 DTV Avanado, o elemento <transition> especificado no elemento <transitionBase> e permite que um padro (template) de transio seja definido. Cada elemento <transition> define um padro nico de transio e deve obrigatoriamente ter um atributo id para que possa ser referenciado dentro de um elemento <descriptor>.
61
Sete atributos do elemento <transition> so derivados da especificao do mdulo BasicTransitions de SMIL: type; subtype; dur; startProgress; endProgress; direction; e fadeColor. As transies so classificadas de acordo com uma taxonomia de dois nveis: tipos e subtipos. Cada tipo de transio descreve um grupo de transies que so intimamente relacionadas. Dentro desse tipo, cada uma das transies individuais associada a um subtipo que enfatiza as caractersticas distintas da transio. O atributo type obrigatrio e utilizado para especificar a transio geral. Se o tipo nomeado no for suportado pelo formatador NCL, a transio deve obrigatoriamente ser ignorada. Isso no uma condio de erro, pois as implementaes so livres para ignorar transies. O atributo subtype fornece o controle especfico para a transio. Esse atributo opcional e, se especificado, deve obrigatoriamente ser um dos subtipos de transio apropriados para o tipo correspondente. Se esse atributo no for especificado, a transio deve obrigatoriamente ser revertida para o subtipo default do tipo especificado. Apenas os subtipos para os cinco tipos de transio obrigatrios, listados na Tabela 36, devem obrigatoriamente ser suportados; os outros tipos e subtipos definidos na especificao SMIL so opcionais. Tabela 36 Tipos e subtipos de transio exigidos Tipo de transition barWipe irisWipe clockWipe snakeWipe fade Subtipo default leftToRight rectangle clockwiseTwelve topLeftHorizontal crossfade
O atributo dur especifica a durao da transio. A durao default de 1 s. O atributo startProgress especifica a quantidade de efeito de transio do incio da execuo. Os valores permitidos so nmeros reais na faixa [0.0,1.0]. Por exemplo, pode-se querer iniciar um crossfade com imagem destino j transparente em 30 % inicialmente. Para esse caso, o startProgress seria 0.3. O valor default 0.0. O atributo endProgress especifica a quantidade de efeito de transio ao trmino da execuo. Os valores permitidos so nmeros reais na faixa [0.0,1.0] e o valor desse atributo deve obrigatoriamente ser maior ou igual ao valor do atributo startProgress. Se endProgress for igual a startProgress, ento a transmisso permanece em um valor fixo pela durao da transmisso. O valor default 1,0. O atributo direction especifica a direo em que ocorrer a transio. Os valores permitidos so forward e reverse. O valor default forward. Nem todas as transies tero interpretaes reversas significantes. Por exemplo, um crossfade no uma transio geomtrica e, portanto, no tem interpretao de direo reversa. As transies que no tm interpretao reversa devem ter o atributo direction ignorado e o valor default "forward" assumido. Se o valor do atributo type for fade e o valor do atributo subtype for fadeToColor ou fadeFromColor (valores de subtipo que no so obrigatrios em uma implementao Ginga), ento o atributo fadeColor especifica a cor final ou inicial do fade. Se o valor do atributo type no for fade, ou se o valor do atributo subtype no for fadeToColor ou fadeFromColor, ento o atributo fadeColor deve obrigatoriamente ser ignorado. O valor default black. O mdulo Transition tambm define os atributos a serem utilizados nos elementos <descriptor>, para os padres de transio definidos pelos elementos <transition>: atributos transIn e transOut. As transies especificadas com um atributo transIn iniciaro no comeo da durao ativa dos elementos de mdia (quando a apresentao do objeto inicia). As transies especificadas com um atributo transOut terminaro no final da durao ativa dos elementos de mdia (quando a apresentao do objeto transita do estado ocorrendo para preparado).
62
Os atributos transIn e transOut so adicionados aos elementos <descriptor>. O valor default de ambos os atributos uma string vazia, que indica que, obrigatoriamente, nenhuma transio deve ser realizada. O valor dos atributos transIn e transOut uma lista separada por ponto e vrgula dos identificadores de transio. Cada um dos identificadores deve obrigatoriamente corresponder ao valor do identificador XML de um dos elementos de transio anteriormente definidos no elemento <transitionBase>. O objetivo da lista separada por ponto e vrgula permitir que os autores especifiquem um conjunto de transies alternativas (fallback) se a transio preferida no estiver disponvel. A primeira transio na lista deve ser realizada se o agente do usurio implementar esta transio. Se essa transio no estiver disponvel, ento a segunda transio na lista deve ser realizada, e assim sucessivamente. Se o valor do atributo transIn ou transOut no corresponder ao valor do identificador XML de nenhum dos elementos de transio previamente definidos, ento h um erro. Em caso de ocorrer esse erro, o valor do atributo que deve ser considerado como sendo uma string vazia e, ento, obrigatoriamente, nenhuma transio deve ser realizada. Todas as transies definidas no mdulo Transition aceitam quatro atributos adicionais (vindos da especificao do mdulo TransitionModifiers de SMIL) que podem ser utilizados para controlar a aparncia das transies. O atributo horRepeat especifica quantas vezes ser realizado o padro de transies ao longo do eixo horizontal. O valor default 1 (o padro ocorre uma vez horizontalmente). O atributo vertRepeat especifica quantas vezes ser realizado o padro de transio ao longo do eixo vertical. O valor default 1 (o padro ocorre uma vez verticalmente). O atributo borderWidth especifica a largura de uma borda gerada ao longo de uma rea apagada. Os valores permitidos so inteiros maiores ou iguais a 0. Se o valor de borderWidth for igual a 0, ento convm que nenhuma borda seja gerada ao longo da rea apagada. O valor default 0. Se o valor do atributo type no for "fade", ento o atributo borderColor especifica o contedo de uma borda gerada ao longo de uma rea apagada. Se o valor desse atributo for uma cor, ento a borda gerada preenchida com a cor definida. Se o valor deste atributo for blend, ento a borda gerada uma mistura aditiva (ou blur) das fontes de mdia. O valor default para esse atributo black. O elemento do mdulo Transition estendido, seus elementos-filhos e seus atributos devem obrigatoriamente estar de acordo com a Tabela 37. Tabela 37 Mdulo Transition estendido Elementos transition Atributos id, type, subtype, dur, startProgress, endProgress, direction, fadeColor, horRepeat, vertRepeat, borderWidth, borderColor vazio Contedo
7.2.15 rea funcional Metainformation Uma metainformao no contm informaes de contedo utilizadas ou exibidas durante a apresentao de um documento. Ao invs disso, contm informaes sobre o contedo utilizado ou exibido. A rea funcional Metainformation composta pelo mdulo metainformation, derivado do mdulo Metainformation SMIL.
NOTA Pode-se consultar o SMIL 2.1 Specification:2005 para outras informaes.
O mdulo metainformation contm dois elementos que permitem a descrio de documentos NCL. O elemento <meta> especifica um nico par de propriedade/valor nos atributos name e content, respectivamente. O elemento <metadata> contm informaes que tambm se relacionam com a metainformao do documento. Ele atua como o elemento raiz da rvore RDF. O elemento <metadata> pode ter como elementos-filhos: elementos RDF e seus subelementos.
NOTA Pode-se consultar a RDF:1999 para outras informaes.
63
Os elementos do mdulo Metainformation, seus elementos-filhos e seus atributos devem obrigatoriamente estar de acordo com a Tabela 38. Tabela 38 Mdulo Meta-Information estendido Elementos meta metadata empty Atributos name, content vazio RDF tree Contedo
7.3
7.3.1
Cada perfil NCL pode agrupar um subconjunto de mdulos NCL, permitindo a criao de linguagens de acordo com as necessidades dos usurios. Qualquer documento em conformidade com os perfis NCL deve obrigatoriamente ter o elemento <ncl> como seu elemento-raiz. O perfil NCL 3.0 completo, tambm chamado de perfil Linguagem NCL 3.0, o perfil completo da linguagem NCL 3.0. Ele compreende todos os mdulos NCL (inclusive os discutidos em 7.2) e fornece todas as facilidades para a autoria declarativa de documentos NCL. Os perfis definidos para o SBTVD so: a) perfil NCL 3.0 DTV Avanado: o perfil NCL 3.0 DTV Avanado inclui os mdulos: Structure, Layout, Media, Context, MediaContentAnchor, CompositeNodeInterface, PropertyAnchor, SwitchInterface, Descriptor, Linking, CausalConnectorFunctionality, ConnectorBase, TestRule, TestRuleUse, ContentControl, DescriptorControl, Timing, Import, EntityReuse, ExtendedEntityReuse KeyNavigation, Animation, TransitionBase, Transition e Meta-Information da NCL 3.0. As tabelas apresentadas em 7.2 mostram cada elemento de cada mdulo, j estendidos pelos atributos e elementos filhos herdados de outros mdulos por esse perfil (ver os esquemas XML em 7.3.2); perfil NCL 3.0 CausalConnector: o perfil CausalConnector permite a criao de conectores simples hipermdia. O perfil inclui os mdulos Structure, CausalConnectorFunctionality e ConnectorBase. No perfil, o elemento <body> do mdulo Structure no utilizado (ver os esquemas XML em 7.3.3); perfil NCL 3.0 DTV Bsico: o perfil NCL 3.0 DTV Bsico inclui os mdulos Structure, Layout, Media, Context, MediaContentAnchor, CompositeNodeInterface, PropertyAnchor, SwitchInterface, Descriptor, Linking, CausalConnectorFunctionality, ConnectorBase, TestRule, TestRuleUse, ContentControl, DescriptorControl, Timing, Import, EntityReuse, ExtendedEntityReuse e KeyNavigation. As tabelas apresentadas em 7.3.4 mostram cada elemento de cada mdulo desse perfil, j estendidos pelos atributos e elementos-filhos herdados de outros mdulos (ver os esquemas XML em 7.3.5).
b)
c)
64
7.3.2
NCL30EDTV.xsd
<!-XML Schema for the NCL Language This is NCL Copyright: 2000-2005 PUC-RIO/LABORATORIO TELEMIDIA, All Rights Reserved. See http://www.telemidia.puc-rio.br Public URI: http://www.ncl.org.br/NCL3.0/profiles/NCL30EDTV.xsd Author: TeleMidia Laboratory Revision: 19/09/2006 --> <schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:animation="http://www.ncl.org.br/NCL3.0/Animation" xmlns:compositeInterface="http://www.ncl.org.br/NCL3.0/CompositeNodeInterface" xmlns:causalConnectorFunctionality="http://www.ncl.org.br/NCL3.0/CausalConnectorFunctionality" xmlns:connectorBase="http://www.ncl.org.br/NCL3.0/ConnectorBase" xmlns:connectorCausalExpression="http://www.ncl.org.br/NCL3.0/ConnectorCausalExpression" xmlns:contentControl="http://www.ncl.org.br/NCL3.0/ContentControl" xmlns:context="http://www.ncl.org.br/NCL3.0/Context" xmlns:descriptor="http://www.ncl.org.br/NCL3.0/Descriptor" xmlns:entityReuse="http://www.ncl.org.br/NCL3.0/EntityReuse" xmlns:extendedEntityReuse="http://www.ncl.org.br/NCL3.0/ExtendedEntityReuse" xmlns:descriptorControl="http://www.ncl.org.br/NCL3.0/DescriptorControl" xmlns:import="http://www.ncl.org.br/NCL3.0/Import" xmlns:keyNavigation="http://www.ncl.org.br/NCL3.0/KeyNavigation" xmlns:layout="http://www.ncl.org.br/NCL3.0/Layout" xmlns:linking="http://www.ncl.org.br/NCL3.0/Linking" xmlns:media="http://www.ncl.org.br/NCL3.0/Media" xmlns:mediaAnchor="http://www.ncl.org.br/NCL3.0/MediaContentAnchor" xmlns:propertyAnchor="http://www.ncl.org.br/NCL3.0/PropertyAnchor" xmlns:structure="http://www.ncl.org.br/NCL3.0/Structure" xmlns:switchInterface="http://www.ncl.org.br/NCL3.0/SwitchInterface" xmlns:testRule="http://www.ncl.org.br/NCL3.0/TestRule" xmlns:testRuleUse="http://www.ncl.org.br/NCL3.0/TestRuleUse" xmlns:timing="http://www.ncl.org.br/NCL3.0/Timing" xmlns:transitionBase="http://www.ncl.org.br/NCL3.0/TransitionBase" xmlns:metainformation="http://www.ncl.org.br/NCL3.0/Metainformation" xmlns:transition="http://www.ncl.org.br/NCL3.0/Transition" xmlns:metainformation="http://www.w3.org/2001/SMIL20/Metainformation" xmlns:basicTransition="http://www.w3.org/2001/SMIL20/BasicTransitions" xmlns:profile="http://www.ncl.org.br/NCL3.0/EDTVProfile" targetNamespace="http://www.ncl.org.br/NCL3.0/EDTVProfile" elementFormDefault="qualified" attributeFormDefault="unqualified" > <!-- import the definitions in the modules namespaces --> <import namespace="http://www.ncl.org.br/NCL3.0/Animation" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Animation.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/CompositeNodeInterface" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30CompositeNodeInterface.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/CausalConnectorFunctionality" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30CausalConnectorFunctionality.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/ConnectorBase" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30ConnectorBase.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/ConnectorCausalExpression" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30ConnectorCausalExpression.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/ContentControl" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30ContentControl.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Context" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Context.xsd"/>
65
<import namespace="http://www.ncl.org.br/NCL3.0/Descriptor" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Descriptor.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/DescriptorControl" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30DescriptorControl.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/EntityReuse" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30EntityReuse.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/ExtendedEntityReuse" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30ExtendedEntityReuse.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Import" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Import.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/KeyNavigation" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30KeyNavigation.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Layout" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Layout.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Linking" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Linking.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Media" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Media.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/MediaContentAnchor" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30MediaContentAnchor.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/PropertyAnchor" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30PropertyAnchor.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Structure" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Structure.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/SwitchInterface" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30SwitchInterface.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/TestRule" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30TestRule.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/TestRuleUse" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30TestRuleUse.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Timing" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Timing.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/TransitionBase" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30TransitionBase.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Metainformation" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Metainformation.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Transition" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Transition.xsd"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Structure --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends ncl element --> <element name="ncl" substitutionGroup="structure:ncl"/> <!-- extends head element --> <complexType name="headType"> <complexContent> <extension base="structure:headPrototype"> <sequence> <element ref="profile:importedDocumentBase" minOccurs="0" maxOccurs="1"/> <element ref="profile:ruleBase" minOccurs="0" maxOccurs="1"/> <element ref="profile:transitionBase" minOccurs="0" maxOccurs="1"/> <element ref="profile:regionBase" minOccurs="0" maxOccurs="unbounded"/> <element ref="profile:descriptorBase" minOccurs="0" maxOccurs="1"/> <element ref="profile:connectorBase" minOccurs="0" maxOccurs="1"/> <element ref="profile:meta" minOccurs="0" maxOccurs="unbounded"/> <element ref="profile:metadata" minOccurs="0" maxOccurs="unbounded"/> </sequence> </extension> </complexContent> </complexType>
66
<element name="head" type="profile:headType" substitutionGroup="structure:head"/> <!-- extends body element --> <complexType name="bodyType"> <complexContent> <extension base="structure:bodyPrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <group ref="profile:contextInterfaceElementGroup"/> <element ref="profile:media"/> <element ref="profile:context"/> <element ref="profile:switch"/> <element ref="profile:link"/> <element ref="profile:meta"/> <element ref="profile:metadata"/> </choice> </extension> </complexContent> </complexType> <element name="body" type="profile:bodyType" substitutionGroup="structure:body"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Layout --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends regionBase element --> <complexType name="regionBaseType"> <complexContent> <extension base="layout:regionBasePrototype"> <choice minOccurs="1" maxOccurs="unbounded"> <element ref="profile:importBase"/> <element ref="profile:region"/> </choice> </extension> </complexContent> </complexType> <complexType name="regionType"> <complexContent> <extension base="layout:regionPrototype"> </extension> </complexContent> </complexType> <element name="regionBase" type="profile:regionBaseType" substitutionGroup="layout:regionBase"/> <element name="region" type="profile:regionType" substitutionGroup="layout:region"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Media --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends Media elements --> <!-- media interface element groups --> <group name="mediaInterfaceElementGroup"> <choice> <element ref="profile:area"/> <element ref="profile:property"/> </choice> </group> <complexType name="mediaType"> <complexContent> <extension base="media:mediaPrototype">
67
<choice minOccurs="0" maxOccurs="unbounded"> <group ref="profile:mediaInterfaceElementGroup"/> </choice> <attributeGroup ref="descriptor:descriptorAttrs"/> <attributeGroup ref="entityReuse:entityReuseAttrs"/> <attributeGroup ref="extendedEntityReuse:extendedEntityReuseAttrs"/> </extension> </complexContent> </complexType> <element name="media" type="profile:mediaType" substitutionGroup="media:media"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Context --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends context element --> <!-- composite node interface element groups --> <group name="contextInterfaceElementGroup"> <choice> <element ref="profile:port"/> <element ref="profile:property"/> </choice> </group> <complexType name="contextType"> <complexContent> <extension base="context:contextPrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <group ref="profile:contextInterfaceElementGroup"/> <element ref="profile:media"/> <element ref="profile:context"/> <element ref="profile:link"/> <element ref="profile:switch"/> <element ref="profile:meta"/> <element ref="profile:metadata"/> </choice> <attributeGroup ref="entityReuse:entityReuseAttrs"/> </extension> </complexContent> </complexType> <element name="context" type="profile:contextType" substitutionGroup="context:context"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- MediaContentAnchor --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends area element --> <complexType name="componentAnchorType"> <complexContent> <extension base="mediaAnchor:componentAnchorPrototype"> </extension> </complexContent> </complexType> <element name="area" type="profile:componentAnchorType" substitutionGroup="mediaAnchor:area"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- CompositeNodeInterface --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends port element --> <complexType name="compositeNodePortType"> <complexContent>
68
<extension base="compositeInterface:compositeNodePortPrototype"> </extension> </complexContent> </complexType> <element name="port" type="profile:compositeNodePortType" substitutionGroup="compositeInterface:port"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- PropertyAnchor --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends property element --> <complexType name="propertyAnchorType"> <complexContent> <extension base="propertyAnchor:propertyAnchorPrototype"> </extension> </complexContent> </complexType> <element name="property" type="profile:propertyAnchorType" substitutionGroup="propertyAnchor:property"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- SwitchInterface --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends switchPort element --> <complexType name="switchPortType"> <complexContent> <extension base="switchInterface:switchPortPrototype"> </extension> </complexContent> </complexType> <element name="mapping" substitutionGroup="switchInterface:mapping"/> <element name="switchPort" type="profile:switchPortType" substitutionGroup="switchInterface:switchPort"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Descriptor --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- substitutes descriptorParam element --> <element name="descriptorParam" substitutionGroup="descriptor:descriptorParam"/> <!-- extends descriptor element --> <complexType name="descriptorType"> <complexContent> <extension base="descriptor:descriptorPrototype"> <attributeGroup ref="layout:regionAttrs"/> <attributeGroup ref="timing:explicitDurAttrs"/> <attributeGroup ref="timing:freezeAttrs"/> <attributeGroup ref="keyNavigation:keyNavigationAttrs"/> <attributeGroup ref="transition:transAttrs"/> </extension> </complexContent> </complexType> <element name="descriptor" type="profile:descriptorType" substitutionGroup="descriptor:descriptor"/> <!-- extends descriptorBase element --> <complexType name="descriptorBaseType"> <complexContent> <extension base="descriptor:descriptorBasePrototype"> <choice minOccurs="1" maxOccurs="unbounded">
69
<element ref="profile:importBase"/> <element ref="profile:descriptor"/> <element ref="profile:descriptorSwitch"/> </choice> </extension> </complexContent> </complexType> <element name="descriptorBase" type="profile:descriptorBaseType" substitutionGroup="descriptor:descriptorBase"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Linking --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- substitutes linkParam and bindParam elements --> <element name="linkParam" substitutionGroup="linking:linkParam"/> <element name="bindParam" substitutionGroup="linking:bindParam"/> <!-- extends bind element and link element, as a consequence--> <complexType name="bindType"> <complexContent> <extension base="linking:bindPrototype"> <attributeGroup ref="descriptor:descriptorAttrs"/> </extension> </complexContent> </complexType> <element name="bind" type="profile:bindType" substitutionGroup="linking:bind"/> <!-- extends link element --> <complexType name="linkType"> <complexContent> <extension base="linking:linkPrototype"> </extension> </complexContent> </complexType> <element name="link" type="profile:linkType" substitutionGroup="linking:link"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Connector --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends connectorBase element --> <complexType name="connectorBaseType"> <complexContent> <extension base="connectorBase:connectorBasePrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <element ref="profile:importBase"/> <element ref="profile:causalConnector" /> </choice> </extension> </complexContent> </complexType> <complexType name="simpleActionType"> <complexContent> <extension base="connectorCausalExpression:simpleActionPrototype"> <attributeGroup ref="animation:animationAttrs"/> </extension> </complexContent> </complexType> <element name="connectorBase" type="profile:connectorBaseType" substitutionGroup="connectorBase:connectorBase"/>
70
<element name="causalConnector" substitutionGroup="causalConnectorFunctionality:causalConnector"/> <element name="connectorParam" substitutionGroup="causalConnectorFunctionality:connectorParam"/> <element name="simpleCondition" substitutionGroup="causalConnectorFunctionality:simpleCondition"/> <element name="compoundCondition" substitutionGroup="causalConnectorFunctionality:compoundCondition"/> <element name="simpleAction" type="profile:simpleActionType" substitutionGroup="causalConnectorFunctionality:simpleAction"/> <element name="compoundAction" substitutionGroup="causalConnectorFunctionality:compoundAction"/> <element name="assessmentStatement" substitutionGroup="causalConnectorFunctionality:assessmentStatement"/> <element name="attributeAssessment" substitutionGroup="causalConnectorFunctionality:attributeAssessment"/> <element name="valueAssessment" substitutionGroup="causalConnectorFunctionality:valueAssessment"/> <element name="compoundStatement" substitutionGroup="causalConnectorFunctionality:compoundStatement"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- TestRule --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends rule element --> <complexType name="ruleType"> <complexContent> <extension base="testRule:rulePrototype"> </extension> </complexContent> </complexType> <element name="rule" type="profile:ruleType" substitutionGroup="testRule:rule"/> <!-- extends compositeRule element --> <complexType name="compositeRuleType"> <complexContent> <extension base="testRule:compositeRulePrototype"> </extension> </complexContent> </complexType> <element name="compositeRule" type="profile:compositeRuleType" substitutionGroup="testRule:compositeRule"/> <!-- extends ruleBase element --> <complexType name="ruleBaseType"> <complexContent> <extension base="testRule:ruleBasePrototype"> <choice minOccurs="1" maxOccurs="unbounded"> <element ref="profile:importBase"/> <element ref="profile:rule"/> <element ref="profile:compositeRule"/> </choice> </extension> </complexContent> </complexType> <element name="ruleBase" type="profile:ruleBaseType" substitutionGroup="testRule:ruleBase"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- TestRuleUse --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends bindRule element --> <complexType name="bindRuleType">
71
<complexContent> <extension base="testRuleUse:bindRulePrototype"> </extension> </complexContent> </complexType> <element name="bindRule" type="profile:bindRuleType" substitutionGroup="testRuleUse:bindRule"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- ContentControl --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends switch element --> <!-- switch interface element groups --> <group name="switchInterfaceElementGroup"> <choice> <element ref="profile:switchPort"/> </choice> </group> <!-- extends defaultComponent element --> <complexType name="defaultComponentType"> <complexContent> <extension base="contentControl:defaultComponentPrototype"> </extension> </complexContent> </complexType> <element name="defaultComponent" type="profile:defaultComponentType" substitutionGroup="contentControl:defaultComponent"/> <complexType name="switchType"> <complexContent> <extension base="contentControl:switchPrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <group ref="profile:switchInterfaceElementGroup"/> <element ref="profile:bindRule"/> <element ref="profile:switch"/> <element ref="profile:media"/> <element ref="profile:context"/> </choice> <attributeGroup ref="entityReuse:entityReuseAttrs"/> </extension> </complexContent> </complexType> <element name="switch" type="profile:switchType" substitutionGroup="contentControl:switch"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- DescriptorControl --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends defaultDescriptor element --> <complexType name="defaultDescriptorType"> <complexContent> <extension base="descriptorControl:defaultDescriptorPrototype"> </extension> </complexContent> </complexType> <element name="defaultDescriptor" type="profile:defaultDescriptorType" substitutionGroup="descriptorControl:defaultDescriptor"/> <!-- extends descriptorSwitch element --> <complexType name="descriptorSwitchType">
72
<complexContent> <extension base="descriptorControl:descriptorSwitchPrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <element ref="profile:descriptor"/> <element ref="profile:bindRule"/> </choice> </extension> </complexContent> </complexType> <element name="descriptorSwitch" type="profile:descriptorSwitchType" substitutionGroup="descriptorControl:descriptorSwitch"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Timing --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Import --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <complexType name="importBaseType"> <complexContent> <extension base="import:importBasePrototype"> </extension> </complexContent> </complexType> <complexType name="importNCLType"> <complexContent> <extension base="import:importNCLPrototype"> </extension> </complexContent> </complexType> <complexType name="importedDocumentBaseType"> <complexContent> <extension base="import:importedDocumentBasePrototype"> </extension> </complexContent> </complexType> <element name="importBase" type="profile:importBaseType" substitutionGroup="import:importBase"/> <element name="importNCL" type="profile:importNCLType" substitutionGroup="import:importNCL"/> <element name="importedDocumentBase" type="profile:importedDocumentBaseType" substitutionGroup="import:importedDocumentBase"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- EntityReuse --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- ExtendedEntityReuse --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- KeyNavigation --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- TransitionBase --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends transitionBase element -->
73
<complexType name="transitionBaseType"> <complexContent> <extension base="transitionBase:transitionBasePrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <element ref="profile:transition"/> <element ref="profile:importBase"/> </choice> </extension> </complexContent> </complexType> <element name="transitionBase" type="profile:transitionBaseType" substitutionGroup="transitionBase:transitionBase"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Transition --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <element name="transition" substitutionGroup="transition:transition"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Metainformation --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <element name="meta" substitutionGroup="metainformation:meta"/> <element name="metadata" substitutionGroup="metainformation:metadata"/> </schema>
7.3.3
CausalConnector.xsd
<!-XML Schema for the NCL Language This is NCL Copyright: 2000-2005 LABORATORIO TELEMIDIA, All Rights Reserved. See http://www.telemidia.puc-rio.br Public URI: http://www.ncl.org.br/NCL3.0/profiles/CausalConnector.xsd Author: TeleMidia Laboratory Revision: 19/09/2006 --> <schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:causalConnectorFunctionality="http://www.ncl.org.br/NCL3.0/CausalConnectorFunctionality" xmlns:connectorBase="http://www.ncl.org.br/NCL3.0/ConnectorBase" xmlns:structure="http://www.ncl.org.br/NCL3.0/Structure" xmlns:import="http://www.ncl.org.br/NCL3.0/Import" xmlns:profile="http://www.ncl.org.br/NCL3.0/CausalConnectorProfile" targetNamespace="http://www.ncl.org.br/NCL3.0/CausalConnectorProfile" elementFormDefault="qualified" attributeFormDefault="unqualified"> <!-- import the definitions in the modules namespaces --> <import namespace="http://www.ncl.org.br/NCL3.0/CausalConnectorFunctionality" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30CausalConnectorFunctionality.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/ConnectorBase" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30ConnectorBase.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Structure" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Structure.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Import" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Import.xsd"/>
74
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Structure --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends ncl element --> <complexType name="nclType"> <complexContent> <restriction base="structure:nclPrototype"> <sequence> <element ref="structure:head" minOccurs="0" maxOccurs="1"/> <element ref="structure:body" minOccurs="0" maxOccurs="0"/> </sequence> </restriction> </complexContent> </complexType> <element name="ncl" type="profile:nclType" substitutionGroup="structure:ncl"/> <!-- extends head element --> <complexType name="headType"> <complexContent> <extension base="structure:headPrototype"> <all> <element ref="profile:connectorBase" /> </all> </extension> </complexContent> </complexType> <element name="head" type="profile:headType" substitutionGroup="structure:head"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- XConnector --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends connectorBase element --> <complexType name="connectorBaseType"> <complexContent> <extension base="connectorBase:connectorBasePrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <element ref="profile:importBase"/> <element ref="profile:causalConnector" /> </choice> </extension> </complexContent> </complexType> <element name="connectorBase" type="profile:connectorBaseType" substitutionGroup="connectorBase:connectorBase"/> <element name="causalConnector" substitutionGroup="causalConnectorFunctionality:causalConnector"/> <element name="connectorParam" substitutionGroup="causalConnectorFunctionality:connectorParam"/> <element name="simpleCondition" substitutionGroup="causalConnectorFunctionality:simpleCondition"/> <element name="compoundCondition" substitutionGroup="causalConnectorFunctionality:compoundCondition"/> <element name="simpleAction" substitutionGroup="causalConnectorFunctionality:simpleAction"/> <element name="compoundAction" substitutionGroup="causalConnectorFunctionality:compoundAction"/> <element name="assessmentStatement" substitutionGroup="causalConnectorFunctionality:assessmentStatement"/>
75
<element name="attributeAssessment" substitutionGroup="causalConnectorFunctionality:attributeAssessment"/> <element name="valueAssessment" substitutionGroup="causalConnectorFunctionality:valueAssessment"/> <element name="compoundStatement" substitutionGroup="causalConnectorFunctionality:compoundStatement"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- ImportBase --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <element name="importBase" substitutionGroup="import:importBase"/> </schema>
7.3.4
Os elementos e seus atributos, utilizados no perfil NCL 3.0 DTV Bsico, so apresentados nas Tabelas 39 a 55. Salienta-se que os atributos e contedos (elementos-filhos) de elementos podem ser definidos no mdulo em si ou no perfil NCL DTV Bsico que agrupa os mdulos. Os atributos obrigatrios esto sublinhados. Nas Tabelas 39 a 55, os seguintes smbolos so empregados: (?) opcional (zero ou uma ocorrncia), (|) ou (*) zero ou mais ocorrncias, (+) uma ou mais ocorrncias. Tabela 39 Elementos e atributos do mdulo Structure estendido utilizados no perfil DTV Bsico Elementos ncl head body id id, title, xmlns Atributos (head?, body?) (importedDocumentBase? ruleBase?, regionBase*, descriptorBase?, connectorBase?), (port| property| media|context|switch|link)* Contedo
Tabela 40 Elementos e atributos do mdulo Layout estendido utilizados no perfil DTV Bsico Elementos regionBase Region Atributos id, device, region id, title, left, right, top, bottom, height, width, zIndex Contedo (importBase|region)+ (region)*
Tabela 41 Elementos e atributos do mdulo Media estendido utilizados no perfil DTV Bsico Elementos Media Atributos id, src, refer, instance, type, descriptor (area|property)* Contedo
Tabela 42 Elementos e atributos do mdulo Context estendido utilizados no perfil DTV Bsico Elementos Context id, refer Atributos Contedo (port|property|media|context|link|switch)*
Tabela 43 Elementos e atributos do mdulo MediaContentAnchor estendido utilizados no perfil DTV Bsico Elementos area Atributos id, coords, begin, end, text, position, first, last, label vazio Contedo
76
Tabela 44 Elementos e atributos do mdulo CompositeNodeInterface estendido utilizados no perfil DTV Bsico Elementos
Port
Atributos
id, component, interface vazio
Contedo
Tabela 45 Elementos e atributos do mdulo PropertyAnchor estendido utilizados no perfil DTV Bsico Elementos Property name, value Atributos vazio Contedo
Tabela 46 Elementos e atributos do mdulo SwitchInterface estendido utilizados no perfil DTV Bsico Elementos switchPort Mapping id component, interface Atributos mapping+ vazio Contedo
Tabela 47 Elementos e atributos do mdulo Descriptor estendido utilizados no perfil DTV Bsico Elementos Atributos id, player, explicitDur, region, freeze, moveLeft, moveRight, moveUp; moveDown, focusIndex, focusBorderColor; focusBorderWidth; focusBorderTransparency, focusSrc,focusSelSrc, selBorderColor name, value id Contedo
descriptor
(descriptorParam)*
descriptorParam descriptorBase
Tabela 48 Elementos e atributos do mdulo Linking estendido utilizados no perfil DTV Bsico Elementos
Bind bindParam linkParam Link name, value name, value id, xconnector
Atributos
role, component, interface, descriptor (bindParam)* vazio vazio
Contedo
(linkParam*, bind+)
77
Tabela 49 Elementos e atributos do mdulo CausalConnectorFunctionality estendido utilizados no perfil DTV Bsico Elementos causalConnector connectorParam simpleCondition id name, type role, delay, eventType, key, transition, min, max, qualifier operator, delay role, delay, eventType, actionType, value, min, max, qualifier, repeat, repeatDelay operator, delay comparator role, eventType, key, attributeType, offset value operator, isNegated Atributos Contedo (connectorParam*, (simpleCondition | compoundCondition), (simpleAction | compoundAction)) vazio vazio ((simpleCondition | compoundCondition)+, (assessmentStatement | compoundStatement)*) vazio
compoundCondition
Tabela 50 Elementos e atributos do mdulo ConnectorBase estendido utilizados no perfil DTV Bsico Elementos connectorBase id Atributos Contedo (importBase|causalConnector)*
Tabela 51 Elementos e atributos do mdulo TestRule estendido utilizados no perfil DTV Bsico Elementos ruleBase rule compositeRule id id, var, comparator, value id, operator Atributos Contedo (importBase|rule|compositeRule)+ vazio (rule | compositeRule)+
Tabela 52 Elementos e atributos do mdulo TestRuleUse estendido utilizados no perfil DTV Bsico Elementos bindRule Atributos constituent, rule vazio Contedo
78
Tabela 53 Elementos e atributos do mdulo ContentControl estendido utilizados no perfil DTV Bsico Elementos Switch defaultComponent id, refer component Atributos Contedo (defaultComponent?,(switchPort| bindRule|media| context | switch)*) vazio
Tabela 54 Elementos e atributos do mdulo DescriptorControl estendido utilizados no perfil DTV Bsico Elementos descriptorSwitch defaultDescriptor id descriptor Atributos Contedo (defaultDescriptor?, (bindRule | descriptor)*) vazio
Tabela 55 Elementos e atributos do mdulo Import estendido utilizados no perfil DTV Bsico Elementos importBase importedDocumentBase importNCL 7.3.5 Atributos alias, documentURI, region id alias, documentURI, vazio (importNCL)+ vazio Contedo
NCL30BDTV.xsd
<!-XML Schema for the NCL Language This is NCL Copyright: 2000-2005 PUC-RIO/LABORATORIO TELEMIDIA, All Rights Reserved. See http://www.telemidia.puc-rio.br Public URI: http://www.ncl.org.br/NCL3.0/profiles/NCL30BDTV.xsd Author: TeleMidia Laboratory Revision: 19/09/2006 --> <schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:compositeInterface="http://www.ncl.org.br/NCL3.0/CompositeNodeInterface" xmlns:causalConnectorFunctionality="http://www.ncl.org.br/NCL3.0/CausalConnectorFunctionality" xmlns:connectorBase="http://www.ncl.org.br/NCL3.0/ConnectorBase" xmlns:contentControl="http://www.ncl.org.br/NCL3.0/ContentControl" xmlns:context="http://www.ncl.org.br/NCL3.0/Context" xmlns:descriptor="http://www.ncl.org.br/NCL3.0/Descriptor" xmlns:entityReuse="http://www.ncl.org.br/NCL3.0/EntityReuse" xmlns:extendedEntityReuse="http://www.ncl.org.br/NCL3.0/ExtendedEntityReuse" xmlns:descriptorControl="http://www.ncl.org.br/NCL3.0/DescriptorControl" xmlns:import="http://www.ncl.org.br/NCL3.0/Import" xmlns:keyNavigation="http://www.ncl.org.br/NCL3.0/KeyNavigation" xmlns:layout="http://www.ncl.org.br/NCL3.0/Layout" xmlns:linking="http://www.ncl.org.br/NCL3.0/Linking"
79
xmlns:media="http://www.ncl.org.br/NCL3.0/Media" xmlns:mediaAnchor="http://www.ncl.org.br/NCL3.0/MediaContentAnchor" xmlns:propertyAnchor="http://www.ncl.org.br/NCL3.0/PropertyAnchor" xmlns:structure="http://www.ncl.org.br/NCL3.0/Structure" xmlns:switchInterface="http://www.ncl.org.br/NCL3.0/SwitchInterface" xmlns:testRule="http://www.ncl.org.br/NCL3.0/TestRule" xmlns:testRuleUse="http://www.ncl.org.br/NCL3.0/TestRuleUse" xmlns:timing="http://www.ncl.org.br/NCL3.0/Timing" xmlns:profile="http://www.ncl.org.br/NCL3.0/BDTVProfile" targetNamespace="http://www.ncl.org.br/NCL3.0/BDTVProfile" elementFormDefault="qualified" attributeFormDefault="unqualified" > <!-- import the definitions in the modules namespaces --> <import namespace="http://www.ncl.org.br/NCL3.0/CompositeNodeInterface" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30CompositeNodeInterface.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/CausalConnectorFunctionality" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30CausalConnectorFunctionality.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/ConnectorBase" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30ConnectorBase.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/ContentControl" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30ContentControl.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Context" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Context.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Descriptor" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Descriptor.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/DescriptorControl" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30DescriptorControl.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/EntityReuse" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30EntityReuse.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/ExtendedEntityReuse" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30ExtendedEntityReuse.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Import" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Import.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/KeyNavigation" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30KeyNavigation.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Layout" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Layout.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Linking" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Linking.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Media" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Media.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/MediaContentAnchor" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30MediaContentAnchor.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/PropertyAnchor" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30PropertyAnchor.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Structure" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Structure.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/SwitchInterface" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30SwitchInterface.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/TestRule" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30TestRule.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/TestRuleUse" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30TestRuleUse.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Timing" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Timing.xsd"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Structure --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends ncl element --> <element name="ncl" substitutionGroup="structure:ncl"/> <!-- extends head element -->
80
<complexType name="headType"> <complexContent> <extension base="structure:headPrototype"> <sequence> <element ref="profile:importedDocumentBase" minOccurs="0" maxOccurs="1"/> <element ref="profile:ruleBase" minOccurs="0" maxOccurs="1"/> <element ref="profile:regionBase" minOccurs="0" maxOccurs="unbounded"/> <element ref="profile:descriptorBase" minOccurs="0" maxOccurs="1"/> <element ref="profile:connectorBase" minOccurs="0" maxOccurs="1"/> </sequence> </extension> </complexContent> </complexType> <element name="head" type="profile:headType" substitutionGroup="structure:head"/> <!-- extends body element --> <complexType name="bodyType"> <complexContent> <extension base="structure:bodyPrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <group ref="profile:contextInterfaceElementGroup"/> <element ref="profile:media"/> <element ref="profile:context"/> <element ref="profile:switch"/> <element ref="profile:link"/> </choice> </extension> </complexContent> </complexType> <element name="body" type="profile:bodyType" substitutionGroup="structure:body"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Layout --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends regionBase element --> <complexType name="regionBaseType"> <complexContent> <extension base="layout:regionBasePrototype"> <choice minOccurs="1" maxOccurs="unbounded"> <element ref="profile:region"/> <element ref="profile:importBase"/> </choice> </extension> </complexContent> </complexType> <complexType name="regionType"> <complexContent> <extension base="layout:regionPrototype"> </extension> </complexContent> </complexType> <element name="regionBase" type="profile:regionBaseType" substitutionGroup="layout:regionBase"/> <element name="region" type="profile:regionType" substitutionGroup="layout:region"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Media --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends Media elements -->
81
<!-- media interface element groups --> <group name="mediaInterfaceElementGroup"> <choice> <element ref="profile:area"/> <element ref="profile:property"/> </choice> </group> <complexType name="mediaType"> <complexContent> <extension base="media:mediaPrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <group ref="profile:mediaInterfaceElementGroup"/> </choice> <attributeGroup ref="descriptor:descriptorAttrs"/> <attributeGroup ref="entityReuse:entityReuseAttrs"/> <attributeGroup ref="extendedEntityReuse:extendedEntityReuseAttrs"/> </extension> </complexContent> </complexType> <element name="media" type="profile:mediaType" substitutionGroup="media:media"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Context --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends context element --> <!-- composite node interface element groups --> <group name="contextInterfaceElementGroup"> <choice> <element ref="profile:port"/> <element ref="profile:property"/> </choice> </group> <complexType name="contextType"> <complexContent> <extension base="context:contextPrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <group ref="profile:contextInterfaceElementGroup"/> <element ref="profile:media"/> <element ref="profile:context"/> <element ref="profile:link"/> <element ref="profile:switch"/> </choice> <attributeGroup ref="entityReuse:entityReuseAttrs"/> </extension> </complexContent> </complexType> <element name="context" type="profile:contextType" substitutionGroup="context:context"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- MediaContentAnchor --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends area element --> <complexType name="componentAnchorType"> <complexContent> <extension base="mediaAnchor:componentAnchorPrototype"> </extension> </complexContent> </complexType>
82
<element name="area" type="profile:componentAnchorType" substitutionGroup="mediaAnchor:area"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- CompositeNodeInterface --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends port element --> <complexType name="compositeNodePortType"> <complexContent> <extension base="compositeInterface:compositeNodePortPrototype"> </extension> </complexContent> </complexType> <element name="port" type="profile:compositeNodePortType" substitutionGroup="compositeInterface:port"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- PropertyAnchor --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends property element --> <complexType name="propertyAnchorType"> <complexContent> <extension base="propertyAnchor:propertyAnchorPrototype"> </extension> </complexContent> </complexType> <element name="property" type="profile:propertyAnchorType" substitutionGroup="propertyAnchor:property"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- SwitchInterface --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends switchPort element --> <complexType name="switchPortType"> <complexContent> <extension base="switchInterface:switchPortPrototype"> </extension> </complexContent> </complexType> <element name="mapping" substitutionGroup="switchInterface:mapping"/> <element name="switchPort" type="profile:switchPortType" substitutionGroup="switchInterface:switchPort"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Descriptor --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- substitutes descriptorParam element --> <element name="descriptorParam" substitutionGroup="descriptor:descriptorParam"/> <!-- extends descriptor element --> <complexType name="descriptorType"> <complexContent> <extension base="descriptor:descriptorPrototype"> <attributeGroup ref="layout:regionAttrs"/> <attributeGroup ref="timing:explicitDurAttrs"/> <attributeGroup ref="timing:freezeAttrs"/> <attributeGroup ref="keyNavigation:keyNavigationAttrs"/> </extension> </complexContent>
83
</complexType> <element name="descriptor" type="profile:descriptorType" substitutionGroup="descriptor:descriptor"/> <!-- extends descriptorBase element --> <complexType name="descriptorBaseType"> <complexContent> <extension base="descriptor:descriptorBasePrototype"> <choice minOccurs="1" maxOccurs="unbounded"> <element ref="profile:importBase"/> <element ref="profile:descriptor"/> <element ref="profile:descriptorSwitch"/> </choice> </extension> </complexContent> </complexType> <element name="descriptorBase" type="profile:descriptorBaseType" substitutionGroup="descriptor:descriptorBase"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Linking --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- substitutes linkParam and bindParam elements --> <element name="linkParam" substitutionGroup="linking:linkParam"/> <element name="bindParam" substitutionGroup="linking:bindParam"/> <!-- extends bind element and link element, as a consequence--> <complexType name="bindType"> <complexContent> <extension base="linking:bindPrototype"> <attributeGroup ref="descriptor:descriptorAttrs"/> </extension> </complexContent> </complexType> <element name="bind" type="profile:bindType" substitutionGroup="linking:bind"/> <!-- extends link element --> <complexType name="linkType"> <complexContent> <extension base="linking:linkPrototype"> </extension> </complexContent> </complexType> <element name="link" type="profile:linkType" substitutionGroup="linking:link"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Connector --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends connectorBase element --> <complexType name="connectorBaseType"> <complexContent> <extension base="connectorBase:connectorBasePrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <element ref="profile:importBase"/> <element ref="profile:causalConnector" /> </choice> </extension> </complexContent> </complexType> <element name="connectorBase" type="profile:connectorBaseType" substitutionGroup="connectorBase:connectorBase"/>
84
<element name="causalConnector" substitutionGroup="causalConnectorFunctionality:causalConnector"/> <element name="connectorParam" substitutionGroup="causalConnectorFunctionality:connectorParam"/> <element name="simpleCondition" substitutionGroup="causalConnectorFunctionality:simpleCondition"/> <element name="compoundCondition" substitutionGroup="causalConnectorFunctionality:compoundCondition"/> <element name="simpleAction" substitutionGroup="causalConnectorFunctionality:simpleAction"/> <element name="compoundAction" substitutionGroup="causalConnectorFunctionality:compoundAction"/> <element name="assessmentStatement" substitutionGroup="causalConnectorFunctionality:assessmentStatement"/> <element name="attributeAssessment" substitutionGroup="causalConnectorFunctionality:attributeAssessment"/> <element name="valueAssessment" substitutionGroup="causalConnectorFunctionality:valueAssessment"/> <element name="compoundStatement" substitutionGroup="causalConnectorFunctionality:compoundStatement"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- TestRule --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends rule element --> <complexType name="ruleType"> <complexContent> <extension base="testRule:rulePrototype"> </extension> </complexContent> </complexType> <element name="rule" type="profile:ruleType" substitutionGroup="testRule:rule"/> <!-- extends compositeRule element --> <complexType name="compositeRuleType"> <complexContent> <extension base="testRule:compositeRulePrototype"> </extension> </complexContent> </complexType> <element name="compositeRule" type="profile:compositeRuleType" substitutionGroup="testRule:compositeRule"/> <!-- extends ruleBase element --> <complexType name="ruleBaseType"> <complexContent> <extension base="testRule:ruleBasePrototype"> <choice minOccurs="1" maxOccurs="unbounded"> <element ref="profile:importBase"/> <element ref="profile:rule"/> <element ref="profile:compositeRule"/> </choice> </extension> </complexContent> </complexType> <element name="ruleBase" type="profile:ruleBaseType" substitutionGroup="testRule:ruleBase"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- TestRuleUse --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends bindRule element --> <complexType name="bindRuleType"> <complexContent>
85
<extension base="testRuleUse:bindRulePrototype"> </extension> </complexContent> </complexType> <element name="bindRule" type="profile:bindRuleType" substitutionGroup="testRuleUse:bindRule"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- ContentControl --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends switch element --> <!-- switch interface element groups --> <group name="switchInterfaceElementGroup"> <choice> <element ref="profile:switchPort"/> </choice> </group> <!-- extends defaultComponent element --> <complexType name="defaultComponentType"> <complexContent> <extension base="contentControl:defaultComponentPrototype"> </extension> </complexContent> </complexType> <element name="defaultComponent" type="profile:defaultComponentType" substitutionGroup="contentControl:defaultComponent"/> <complexType name="switchType"> <complexContent> <extension base="contentControl:switchPrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <group ref="profile:switchInterfaceElementGroup"/> <element ref="profile:bindRule"/> <element ref="profile:switch"/> <element ref="profile:media"/> <element ref="profile:context"/> </choice> <attributeGroup ref="entityReuse:entityReuseAttrs"/> </extension> </complexContent> </complexType> <element name="switch" type="profile:switchType" substitutionGroup="contentControl:switch"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- DescriptorControl --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends defaultDescriptor element --> <complexType name="defaultDescriptorType"> <complexContent> <extension base="descriptorControl:defaultDescriptorPrototype"> </extension> </complexContent> </complexType> <element name="defaultDescriptor" type="profile:defaultDescriptorType" substitutionGroup="descriptorControl:defaultDescriptor"/> <!-- extends descriptorSwitch element --> <complexType name="descriptorSwitchType"> <complexContent>
86
<extension base="descriptorControl:descriptorSwitchPrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <element ref="profile:descriptor"/> <element ref="profile:bindRule"/> </choice> </extension> </complexContent> </complexType> <element name="descriptorSwitch" type="profile:descriptorSwitchType" substitutionGroup="descriptorControl:descriptorSwitch"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Timing --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Import --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <complexType name="importBaseType"> <complexContent> <extension base="import:importBasePrototype"> </extension> </complexContent> </complexType> <complexType name="importNCLType"> <complexContent> <extension base="import:importNCLPrototype"> </extension> </complexContent> </complexType> <complexType name="importedDocumentBaseType"> <complexContent> <extension base="import:importedDocumentBasePrototype"> </extension> </complexContent> </complexType> <element name="importBase" type="profile:importBaseType" substitutionGroup="import:importBase"/> <element name="importNCL" type="profile:importNCLType" substitutionGroup="import:importNCL"/> <element name="importedDocumentBase" type="profile:importedDocumentBaseType" substitutionGroup="import:importedDocumentBase"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- EntityReuse --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- ExtendedEntityReuse --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- KeyNavigation --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> </schema>
87
8
8.1
A apresentao de um documento NCL requer o controle da sincronizao de vrios objetos de mdia (especificados atravs do elemento <media>). Para cada objeto de mdia, um player (exibidor de mdia) pode ser carregado para o controle do objeto e de seus eventos NCL. Um exibidor de mdia (ou seu adaptador) deve obrigatoriamente ser capaz de receber os comandos de apresentao, controlar as mquinas de estado dos eventos do objeto de mdia controlado e responder s demandas do formatador. Para favorecer a incorporao de players de terceiros dentro da implementao da arquitetura Ginga, um projeto modular do Ginga-NCL recomendado, para separar os players da mquina de apresentao (formatador NCL). A Figura 4 sugere uma organizao modular para a implementao Ginga-NCL. Os exibidores so mdulos plug-in da mquina de apresentao. Por ser interessante utilizar os players j existentes, que possam ter interfaces proprietrias que no sejam compatveis com as exigidas pela mquina de apresentao, ser necessrio desenvolver mdulos para fazer as adaptaes necessrias. Nesse caso, o exibidor ser constitudo de um adaptador alm do exibidor no-conforme em si.
Exibidor no-conforme API de exibidor proprietria Exibidor de mdia Exibidor de mdia Adaptador Ginga API para exibidores de mdia Mquina de apresentao Ginga-NCL
8.2
8.2.1
Antes de enviar a instruo start, recomenda-se que o formatador encontre o exibidor de mdia mais apropriado, com base no tipo de contedo a ser exibido. Para tanto, o formatador leva em considerao o atributo player do elemento <descriptor> associado com o objeto de mdia a ser exibido. Se esse atributo no for especificado, o formatador deve obrigatoriamente levar em conta o atributo type do elemento <media>. Se esse atributo tambm no for especificado, o formatador deve obrigatoriamente considerar a extenso do arquivo especificado no atributo src do elemento <media>. A instruo start emitida por um formatador deve obrigatoriamente informar ao exibidor de mdia os seguintes parmetros: o objeto de mdia a ser controlado, seu descritor associado, uma lista de eventos (apresentao, seleo ou atribuio) que precisam ser monitorados pelo exibidor de mdia, o evento de apresentao a ser iniciado (chamado evento principal), um tempo de compensao (offset-time) opcional e um tempo de retardo, opcional.
88
Um objeto de mdia deve obrigatoriamente ser derivado de um elemento <media>, cujo atributo src deve obrigatoriamente ser usado, pelo exibidor de mdia, para localizar o contedo e iniciar a apresentao. Se o contedo no puder ser localizado, ou se o exibidor de mdia no souber como lidar com o tipo de contedo, o exibidor de mdia deve obrigatoriamente encerrar a operao de iniciao sem realizar nenhuma ao. O descritor a ser utilizado deve obrigatoriamente ser escolhido pelo formatador seguindo as diretrizes especificadas no documento NCL. Se a instruo start resultar de uma ao de um elo que tenha um descritor explicitamente declarado em seu elemento <bind> (atributo descritor do elemento <bind>), o descritor resultante informado pelo formatador deve obrigatoriamente mesclar os atributos do descritor especificado pelo <bind> com os atributos do descritor especificado no elemento <media> correspondente, se esse atributo tiver sido especificado. Para atributos em comum, a informao do descritor do <bind> deve obrigatoriamente sobrepor os dados do descritor da <media>. Se o elemento <bind> no contiver um descritor explcito, o descritor informado pelo formatador deve obrigatoriamente ser o descritor especificado pelo elemento <media>, se o atributo tiver sido especificado. Caso contrrio, um descritor default para o tipo de <media> especfico deve obrigatoriamente ser escolhido pelo formatador. Convm que a lista de eventos a serem monitorados por um exibidor de mdia tambm seja computada pelo formatador, levando em conta a especificao do documento NCL. Ele deve obrigatoriamente checar todos os elos dos quais participa o objeto de mdia e o descritor resultante. Ao computar os eventos a serem monitorados, o formatador deve obrigatoriamente considerar a perspectiva do objeto de mdia, isto , o caminho dos vrios elementos <body> e <context> para alcanar em profundidade o elemento <media> correspondente. Convm que apenas elos contidos nesses elementos <body> e <context> sejam considerados na computao dos eventos monitorados. O parmetro offset-time opcional e tem zero como seu valor default. O parmetro significativo somente para mdia contnua ou esttica com durao explcita. Nesse caso, o parmetro define um tempo de compensao, desde o incio (beginning-time) do evento principal, a partir do qual a apresentao desse evento deve ser imediatamente iniciada (isto , ele comanda o exibidor para pular para o beginning-time + offset-time). Obviamente, o valor do offset-time deve obrigatoriamente ser menor que a durao do evento principal. Se o offset-time for maior que zero, o exibidor de mdia deve obrigatoriamente colocar o evento principal no estado ocorrendo (occurring), mas a transio de incio (starts) do evento obrigatoriamente no deve ser notificada. Se o offset-time for zero, o exibidor de mdia deve obrigatoriamente colocar o evento principal no estado ocorrendo e notificar a ocorrncia da transio de incio. Os eventos que teriam seus tempos de trmino anteriores ao tempo de incio do evento principal e eventos que teriam seus tempos de incio aps o tempo de trmino do evento principal no precisam ser monitorados pelo exibidor de mdia (convm que o formatador faa essa verificao quando construir a lista de eventos monitorados). Os eventos monitorados que tm tempos de incio antes do tempo de incio do evento principal e tempos de trmino aps o tempo de incio do evento principal devem obrigatoriamente ser colocados no estado de ocorrendo, mas suas transies de incio obrigatoriamente no devem ser notificadas (elos que dependem dessa transio obrigatoriamente no devem ser disparados). Os eventos monitorados que teriam seus tempos de trmino aps o tempo de incio do evento principal, mas antes do tempo de incio (beginning-time + offset-time), devem obrigatoriamente ter seu atributo occurrences incrementado, mas as transies de incio e trmino (stops) no devem ser notificadas. Os eventos monitorados que tm seu tempo de incio antes do momento de incio (beginning time + offset-time) e tempo de trmino aps o tempo de incio devem obrigatoriamente ser colocados no estado de ocorrendo, mas a transio de incio correspondente obrigatoriamente no deve ser notificada. O tempo de retardo tambm um parmetro opcional e seu valor default tambm zero. Se maior que zero, esse parmetro contm um tempo a ser esperado pelo exibidor de mdia antes de iniciar sua apresentao. Esse parmetro deve ser considerado apenas se o parmetro de offset-time for igual a zero. Se um exibidor de mdia receber uma instruo de start para um objeto j sendo apresentado (pausado ou no), ele deve obrigatoriamente ignorar a instruo e manter o controle da apresentao em andamento. Neste caso, o elemento <simpleAction> que causou a instruo start no deve causar qualquer transio na mquina de estados do evento a ele associado.
89
8.2.2
Instruo stop
A instruo stop precisa apenas identificar um objeto de mdia que j est sendo controlado. Identificar o objeto de mdia significa identificar o elemento <media>, o descritor correspondente e a perspectiva do objeto de mdia. Assim, se um elemento <simpleAction> com o actionType igual a stop ligado por um elo a uma interface de n, a interface deve ser ignorada quando a ao for executada. Se o objeto no estiver sendo apresentado (isto , se nenhum dos eventos na lista de eventos do objeto estiver no estado occurring ou paused) e o exibidor de mdia no estiver aguardando devido a uma instruo atrasada de start, a instruo stop deve obrigatoriamente ser ignorada. Se o objeto estiver sendo apresentado, o evento principal (evento passado como parmetro quando o objeto de mdia foi iniciado) e todos os eventos monitorados no estado occurring ou paused, com tempo de trmino igual ou anterior ao tempo de trmino do evento principal devem obrigatoriamente transitar para o estado sleeping e suas transies stops devem obrigatoriamente ser notificadas. Os eventos monitorados no estado occurring ou paused com tempo de trmino posterior ao tempo de trmino do evento principal devem obrigatoriamente ser colocados no estado sleeping, mas suas transies stops no devem ser notificadas e seu atributo occurrences no deve ser incrementado. A apresentao do contedo do objeto deve obrigatoriamente ser parada. Se o atributo repetitions do evento for maior que zero, deve obrigatoriamente ser diminudo em um e a apresentao do evento principal deve obrigatoriamente reiniciar aps o tempo entre repeties (o tempo de retardo entre repeties deve obrigatoriamente ter sido transmitido ao exibidor de mdia como parmetro de retardo de incio). Se o objeto de mdia estiver esperando para ser apresentado aps uma instruo start atrasada e se uma instruo stop for emitida, a instruo de start anterior deve obrigatoriamente ser removida.
NOTA Quando todos os objetos de mdia que se referem ao fluxo elementar que transporta o vdeo principal de um programa estiverem no estado sleeping, a exibio do vdeo principal ocupa a tela inteira. S por meio de um objeto de mdia em execuo que o vdeo principal pode ser redimensionado. O mesmo acontece com o udio principal de um programa, quando todos os objetos de mdia que se referem ao fluxo elementar que transporta o udio principal de um programa estiverem no estado sleeping, a exibio do udio principal ocorre com 100 % de seu volume.
8.2.3
Instruo abort
A instruo abort precisa apenas identificar um objeto de mdia que j est sendo controlado. Se um elemento <simpleAction> com o actionType igual a abort ligado por um elo a uma interface de n, a interface deve ser ignorada quando a ao for executada. Se o objeto no estiver sendo apresentado e no estiver esperando para ser apresentado aps uma instruo de start atrasada, a instruo abort deve obrigatoriamente ser ignorada. Se o objeto estiver sendo apresentado, o evento principal e todos os eventos monitorados no estado occurring ou paused devem obrigatoriamente transitar para o estado sleeping, e suas transies aborts devem obrigatoriamente ser notificadas. Qualquer apresentao de contedo deve obrigatoriamente parar.
90
Se o atributo repetitions do evento for maior que zero, deve obrigatoriamente ser colocado em zero e a apresentao do objeto de mdia no deve ser reiniciada. Se o objeto de mdia estiver esperando para ser apresentado aps uma instruo start atrasada e uma instruo abort for emitida, a instruo start deve obrigatoriamente ser removida. 8.2.4 Instruo pause
A instruo pause precisa apenas identificar um objeto de mdia que j est sendo controlado. Se um elemento <simpleAction> com o actionType igual a pause for ligado por um elo a uma interface de n, a interface deve ser ignorada quando a ao for executada. Se o objeto no estiver sendo apresentado (se o evento principal, passado como parmetro quando o objeto de mdia foi iniciado, no estiver no estado occurring) e o exibidor de mdia no estiver esperando pelo retardo de incio, a instruo deve obrigatoriamente ser ignorada. Se o objeto estiver sendo apresentado, o evento principal e todos os eventos monitorados no estado occurring devem obrigatoriamente transitar para o estado paused e suas transies pauses devem obrigatoriamente ser notificadas. A apresentao do objeto deve obrigatoriamente ser pausada e o tempo de pausa decorrido obrigatoriamente no deve ser considerado como parte da durao do objeto. Como exemplo, se um objeto tiver durao explcita de 30 s, e aps 25 s for pausado, mesmo se o objeto permanecer pausado por 5 min, aps o reincio, o evento principal do objeto deve obrigatoriamente permanecer ocorrendo por 5 s. Se o evento principal ainda no estiver ocorrendo porque o exibidor de mdia est esperando pelo retardo de incio, o objeto de mdia deve obrigatoriamente esperar por uma instruo resume para continuar aguardando o retardo de incio. 8.2.5 Instruo resume
A instruo resume precisa apenas identificar um objeto de mdia que j est sendo controlado. Se um elemento <simpleAction> com o actionType igual a resume ligado por um elo a uma interface de n, a interface deve ser ignorada quando a ao for executada. Se o objeto no estiver pausado (se o evento principal, passado como parmetro quando o objeto de mdia foi iniciado, no estiver no estado paused) e o exibidor de mdia no estiver pausado (esperando pelo retardo de incio), a instruo deve obrigatoriamente ser ignorada. Se o exibidor de mdia estiver pausado aguardando o retardo de incio, ele deve obrigatoriamente retomar a exibio a partir do instante em que foi pausado. Se o evento principal estiver no estado paused, o evento principal e todos os eventos monitorados no estado paused devem obrigatoriamente ser colocados no estado occurring e suas transies resumes devem obrigatoriamente ser notificadas. 8.2.6 Instruo start para eventos de atribuio
A instruo start pode ser aplicada a um atributo de um objeto independentemente do fato do objeto estar sendo ou no apresentado (nesse ltimo caso, embora o objeto no esteja sendo apresentado, seu exibidor de mdia j deve obrigatoriamente estar instanciado). No primeiro caso, a instruo start precisa identificar o objeto de mdia sendo controlado, um evento de atribuio monitorado e um valor a ser atribudo ao atributo que definiu o evento. No segundo caso, a instruo tambm deve obrigatoriamente identificar o elemento <descriptor> que ser usado quando da apresentao do objeto (como feito para a instruo start para apresentao). Ao imputar um valor ao atributo, o exibidor de mdia deve obrigatoriamente transitar a mquina de estado do evento de atribuio para o estado occurring e, depois de terminada a atribuio, novamente para o estado sleeping, gerando a transio starts e em seguida a transio stops. Para cada evento de atribuio monitorado, se o exibidor de mdia alterar, por sua prpria conta, o valor correspondente de um atributo, deve obrigatoriamente proceder como se tivesse recebido uma instruo de ajuste externa.
91
8.2.7
Instruo addEvent
A instruo addEvent emitida no caso de recepo de um comando de edio NCL addInterface (ver Seo 11). A instruo precisa apenas identificar um objeto de mdia que j esteja sendo controlado e um novo evento que deva obrigatoriamente ser includo para ser monitorado. Todas as regras aplicadas interseo de eventos monitorados com o evento principal devem obrigatoriamente ser aplicadas ao novo evento. Se o tempo de incio do novo evento for anterior ao tempo atual do objeto e o tempo de trmino do novo evento for posterior ao tempo atual do objeto, o novo evento deve obrigatoriamente ser colocado no mesmo estado do evento principal (occurring ou paused), sem notificar a transio correspondente. 8.2.8 Instruo removeEvent
A instruo removeEvent emitida no caso de recepo de um comando de edio NCL removeInterface. A instruo precisa identificar um objeto de mdia que j esteja sendo controlado e um evento que no mais para ser controlado. O estado do evento deve obrigatoriamente ser colocado no estado sleeping sem gerar nenhuma transio. 8.2.9 Trmino natural de uma apresentao
Eventos de um objeto, com durao explcita ou intrnseca, normalmente terminam suas apresentaes naturalmente, sem precisar de instrues externas. Nesse caso, o exibidor de mdia deve obrigatoriamente transitar o evento para o estado sleeping e notificar a transio stops. O mesmo deve obrigatoriamente ser feito para eventos monitorados no estado occurring com o mesmo tempo de trmino do evento principal ou com tempo de trmino desconhecido, quando o evento principal termina. Os eventos no estado occurring com tempo de trmino posterior ao tempo de trmino do evento principal devem obrigatoriamente ser colocados no estado sleeping sem gerar a transio stops e sem incrementar o atributo occurences. importante ressaltar que, se o evento principal corresponder a uma ncora temporal interna ao objeto, quando a apresentao dessa ncora terminar, toda a apresentao do objeto de mdia deve obrigatoriamente terminar.
8.3 Comportamento esperado dos exibidores de mdia aps instrues aplicadas aos objetos de composio
NOTA Os conceitos estabelecidos nesta subseo tambm se aplicam a elementos <media> do tipo application/x-gingaNCL, que se comportaro como se fossem ns de composio constitudos pelos seus elementos <body>.
8.3.1
Um <simpleCondition> ou <simpleAction> com valor do atributo eventType igual a presentation pode ser associado por um elo a um n de composio (representado por um elemento <context> ou <body>) como um todo (isto , sem que uma de suas interface seja informada). Como normalmente ocorre, a mquina de estado do evento de apresentao definido pelo n de composio deve obrigatoriamente ser controlada como especificado em 7.2.8. De forma anloga, um <attributeAssessment>, com valor de atributo eventType igual a presentation e attributeType igual a state, occurrences ou repetitions, pode ser associado por um elo a um n de composio (representado por um elemento <context> ou <body>) como um todo. Recomenda-se que o valor do atributo derive da mquina de estado do evento de apresentao definido pelo n de composio. Contudo, se uma <simpleAction> com valor de atributo eventType igual a presentation for associada por um elo a um n de composio (representado por um elemento <context> ou <body>) como um todo (ou seja, sem que uma de suas interfaces seja informada), a instruo deve obrigatoriamente ser refletida nas mquinas de estado de evento dos ns filhos da composio.
92
8.3.2
Se um elemento <context> ou <body> participar em um papel (role) action cujo tipo de ao "start", quando essa ao for acionada, a instruo start tambm deve obrigatoriamente ser aplicada a todos os eventos de apresentao mapeados pelas portas dos elementos <context> ou <body>. Se o autor quiser iniciar a apresentao usando uma porta especfica, ele tambm deve obrigatoriamente indicar o id de <port> como valor de interface <bind>. 8.3.3 Parando a apresentao de um contexto
Se um elemento <context> ou <body> participar em um papel (role) action cujo tipo de ao "stop", quando essa ao for acionada, a instruo stop tambm deve obrigatoriamente ser aplicada a todos os eventos de apresentao dos ns-filhos da composio. Se a composio contiver elos sendo avaliados (ou com sua avaliao pausada), as avaliaes devem obrigatoriamente ser suspensas e obrigatoriamente nenhuma ao deve ser acionada. 8.3.4 Abortando a apresentao de um contexto
Se um elemento <context> ou <body> participar em um papel (role) action cujo tipo de ao "abort", quando essa ao for acionada, a instruo abort tambm deve obrigatoriamente ser aplicada a todos os eventos de apresentao dos ns filhos da composio. Se a composio contiver elos sendo avaliados (ou com sua avaliao pausada), as avaliaes devem obrigatoriamente ser suspensas e obrigatoriamente nenhuma ao deve ser acionada. 8.3.5 Pausando a apresentao de um contexto
Se um elemento <context> ou <body> participar em um papel (role) action cujo tipo de ao "pause", quando essa ao for acionada, a instruo pause tambm deve obrigatoriamente ser aplicada a todos os eventos de apresentao dos ns filhos da composio que estejam no estado occurring. Se a composio contiver elos sendo avaliados, todas as avaliaes devem obrigatoriamente ser suspensas at que uma ao resume, stop ou abort seja emitida. Se a composio contiver ns-filhos com eventos de apresentao no estado paused quando a ao paused na composio for emitida, esses ns devem obrigatoriamente ser identificados, porque, se a composio receber uma instruo resume, esses eventos obrigatoriamente no devem ser retomados. 8.3.6 Retomando a apresentao de um contexto
Se um elemento <context> ou <body> participar em um papel (role) action cujo tipo de ao "resume", quando essa ao for acionada, a instruo resume tambm deve obrigatoriamente ser aplicada a todos os eventos de apresentao dos ns filhos da composio que estejam no estado paused, exceto aqueles que j estavam pausados antes da composio ser pausada. Se a composio contiver elos com avaliaes pausadas, elas devem obrigatoriamente ser retomadas.
8.4 Relao entre as mquinas de estado de eventos de apresentao de um n e a mquina de estado do evento de apresentao de seu n de composio pai
NOTA Os conceitos estabelecidos nesta subseo tambm se aplicam a elementos <media> do tipo application/x-gingaNCL, que se comportaro como se fossem ns de composio constitudos pelos seus elementos <body>.
Sempre que o evento de apresentao de um n (mdia ou composio) for para o estado occurring, o evento de apresentao do n de composio que contm o n tambm deve obrigatoriamente entrar no estado occurring.
93
Quando todos os ns-filhos de um n de composio tiverem seus eventos de apresentao no estado sleeping, o evento de apresentao do n de composio tambm deve obrigatoriamente estar no estado sleeping. Os ns de composio no precisam inferir transies aborts a partir de seus ns-filhos. Essas transies nos eventos de apresentao de ns de composio devem obrigatoriamente ocorrer apenas quando instrues so aplicadas diretamente ao seu evento de apresentao (ver 8.3). Quando todos os ns filhos de um n de composio tm seus eventos de apresentao em um estado diferente de occurring e ao menos um dos ns tem seu evento principal no estado paused, o evento de apresentao do n de composio deve tambm estar no estado paused. Se um elemento <switch> for iniciado, mas no definir um componente default e nenhuma das regras <bindRule> referenciadas for avaliada como verdadeira, a apresentao switch obrigatoriamente no deve entrar no estado occurring.
8.5
Objetos procedurais podem ser inseridos em documentos NCL, trazendo capacidades computacionais adicionais aos documentos declarativos. A forma de adicionar objetos procedurais em documentos NCL definir um elemento <media> cujo contedo (localizado pelo atributo src) o cdigo procedural a ser executado. Os perfis EDTV e BDTV da NCL 3.0 permitem que dois tipos de mdia sejam associados com o elemento <media>: application/x-ginga-NCLua, para cdigos procedurais Lua (extenso de arquivo .lua); e application/x-ginga-NCLet, para cdigos procedurais Java (Xlet) (extenso de arquivo .class ou .jar). Autores podem definir elos NCL para iniciar, parar, pausar, retomar ou abortar a execuo de um cdigo procedural. Um exibidor procedural (mquina de execuo da linguagem) deve obrigatoriamente prover a interface do ambiente de execuo procedural com o formatador NCL. Analogamente ao realizado pelos exibidores de contedos de mdia convencional, os exibidores procedurais devem obrigatoriamente controlar as mquinas de estado dos eventos associados com o n procedural NCL (NCLua ou NCLet). Como exemplo, se um cdigo terminar sua execuo, o exibidor deve obrigatoriamente gerar a transio stops na mquina de estado de apresentao do evento correspondente execuo procedural. NCL permite que a execuo do cdigo procedural seja sincronizada com outros objetos NCL (procedurais ou no). Um elemento <media> contendo um cdigo procedural tambm pode definir ncoras (atravs de elementos <area>) e propriedades (atravs de elementos <property>). Um cdigo procedural pode ser associado a elementos <area> (atravs do atributo label). Se elos externos iniciarem, pararem, pausarem, retomarem ou abortarem a apresentao da ncora, callbacks no cdigo procedural devem obrigatoriamente ser disparados. A forma como esses callbacks so definidos responsabilidade de cada cdigo procedural associado com o objeto procedural NCL. Por outro lado, um cdigo procedural pode tambm comandar o incio, parada, pausa, retomada ou aborto dessas ncoras, atravs de uma API oferecida pela linguagem procedural. Essas transies podem ser utilizadas como condies de elos NCL para disparar aes em outros objetos NCL do mesmo documento. Assim, uma sincronizao de duas vias pode ser estabelecida entre o cdigo procedural e o restante do documento NCL. A outra forma que um cdigo procedural pode ser sincronizado com outros objetos NCL atravs de elementos <property>. Um elemento <property> definido como filho de um elemento <media>, representando um cdigo procedural, pode ser mapeado para um trecho de cdigo (funo, mtodo, etc.) ou para um atributo do cdigo. Quando mapeado para um trecho de cdigo, uma ao de elo set aplicada propriedade deve obrigatoriamente causar a execuo do cdigo com os valores atribudos interpretados como parmetros de entrada. O atributo name do elemento <property> deve obrigatoriamente ser utilizado para identificar o trecho de cdigo procedural. Um elemento <property> definido como filho de um elemento <media>, representando um cdigo procedural, tambm pode estar associado a um assessment role de um elo NCL. Nesse caso, o formatador NCL deve obrigatoriamente questionar o valor da propriedade para avaliar a expresso do elo. Se o elemento <property> for mapeado para um atributo de cdigo, seu valor deve obrigatoriamente ser retornado pelo exibidor procedural ao formatador NCL. Se o elemento <property> for mapeado para um atributo de cdigo, seu valor deve
94
obrigatoriamente ser retornado pelo exibidor procedural ao formatador NCL. Se o elemento <property> for mapeado para um trecho de cdigo, ele deve obrigatoriamente ser chamado e o valor do resultado de sua execuo deve obrigatoriamente ser retornado pelo exibidor procedural ao formatador NCL. A instruo start emitida por um formatador deve obrigatoriamente informar ao exibidor procedural os seguintes parmetros: o objeto procedural a ser controlado, seu descritor associado, uma lista de eventos (definidos pelos elementos <area> e <property>, filhos do elemento <media> que define o objeto procedural) que precisam ser monitorados pelo exibidor procedural, o identificador (id) do elemento <area> associado ao cdigo procedural a ser executado, e um tempo de retardo, opcional. A partir do atributo src, o exibidor procedural deve tentar localizar o cdigo procedural e iniciar sua execuo. Se o contedo no puder ser localizado, o exibidor procedural deve obrigatoriamente encerrar a operao de inicializao sem realizar nenhuma ao. Aconselha-se que a lista de eventos a serem monitorados por um exibidor procedural tambm seja computada pelo formatador, levando em conta a especificao do documento NCL. Ele deve obrigatoriamente checar todos os elos dos quais participa o objeto de mdia procedural e o descritor resultante. Ao computar os eventos a serem monitorados, o formatador deve obrigatoriamente considerar a perspectiva do objeto de mdia procedural, isto , o caminho dos vrios elementos <body> e <context> para alcanar em profundidade o elemento <media> correspondente. Convm que apenas elos contidos nesses elementos <body> e <context> sejam considerados na computao dos eventos monitorados. Como com todos os tipos de elemento <media>, o tempo de retardo um parmetro opcional, e seu valor default zero. Se maior que zero, esse parmetro contm um tempo a ser esperado pelo exibidor procedural antes de iniciar a execuo. Diferentemente dos procedimentos realizados para outros tipos de elementos <media>, se um exibidor procedural receber uma instruo start para um evento associado a um elemento <area> e esse evento estiver no estado sleeping, ele deve dar incio execuo do cdigo procedural associado ao elemento, mesmo se outra parte do cdigo procedural do objeto de mdia estiver em execuo (pausado ou no). Contudo, se o evento associado ao elemento <area> alvo estiver no estado occurring ou paused, a instruo start deve ser ignorada pelo exibidor procedural que continuar controlando a execuo anteriormente iniciada. Como conseqncia, diferente do que ocorre para os outros elementos <media>, uma ao <simpleAction> com o atributo actionType igual a stop, pause, resume ou abort deve se ligar, atravs de um elo, a uma interface do n procedural, que no deve ser ignorada quando a ao aplicada. A instruo start emitida por um formatador para um evento associado a um elemento <property> pode ser aplicada a um objeto procedural independentemente do fato dele estar sendo executado ou no (nesse ltimo caso, embora o objeto no esteja sendo executado, seu exibidor procedural deve obrigatoriamente j ter sido instanciado). No primeiro caso, a instruo start precisa identificar o objeto procedural, um evento de atribuio monitorado e um valor a ser passado ao cdigo procedural associado ao evento. No segundo caso, deve obrigatoriamente tambm identificar o elemento <descriptor> que ser usado quando da execuo do objeto (anlogo ao que feito para a instruo start para eventos de apresentao). Para cada evento de atribuio monitorado, se o exibidor procedural trocar por si mesmo o valor do atributo, ele deve proceder obrigatoriamente como se tivesse recebido uma instruo externa de start. Recomenda-se que linguagens procedurais ofeream uma API que permita que os cdigos procedurais questionem quaisquer valores de propriedades predefinidas ou dinmicas do n settings NCL (elemento <media> do tipo application/x-ginga-settings). Contudo, deve-se observar que no permitido atribuir valores a essas propriedades diretamente. Propriedades dos ns do tipo application/x-ginga-settings podem apenas ser modificadas atravs do uso de elos NCL.
95
9
9.1
O ncleo da mquina de apresentao Ginga-NCL composto pelo formatador NCL e seu mdulo Gerenciador de Base Privada. O formatador NCL responsvel por receber um documento NCL e controlar sua apresentao, tentando garantir que as relaes especificadas entre os objetos de mdia sejam respeitadas. O formatador lida com documentos NCL que so coletados dentro de uma estrutura de dados conhecida como base privada. Ginga associa uma base privada a um canal de televiso. Os documentos NCL em uma base privada podem ser iniciados, pausados, retomados, parados e podem referir-se uns aos outros. O Gerenciador de Base Privada responsvel por receber comandos de edio de documentos NCL e pela edio dos documentos NCL ativos (documentos sendo apresentados). Esta subseo trata apenas de comandos de edio enviados pelo canal de difuso terrestre.
NOTA Os mesmos comandos de edio podem tambm ser recebidos pelo canal de interatividade ou por eventos gerados pelos objetos imperativos NCLua e NCLet.
Ginga adota sees MPEG-2 especficas (identificadas pelo campo tableID da Seo MPEG-2) para transportar os comandos de edio em fluxos elementares MPEG-2 TS, quando os comandos so enviados pelo canal de difuso terrestre. Os Comandos de Edio so envelopados em uma estrutura chamada descritor de evento. Cada descritor de evento tem uma estrutura composta basicamente por um id (identificao), uma referncia de tempo e um campo de dados privados. A identificao define univocamente cada evento. A referncia de tempo indica o exato momento de disparar o evento. Um tempo de referncia igual a zero informa que o evento deve obrigatoriamente ser imediatamente disparado aps ser recebido (eventos carregando este tipo de referncia de tempo so comumente conhecidos como eventos do it now). O campo de dados privados oferece suporte para parmetros do evento, como apresentado na Figura 5.
Sintaxe Nmero de bits
16 33 8
8 7 1 8 a 2008 8
Figura 5 Descritor de evento para comandos de edio O campo commandTag identifica univocamente os comandos de edio, como especificado na Tabela 56. Para permitir enviar um comando completo com mais de 255 bytes em mais de um descritor de evento, todos os descritores de um mesmo comando devem obrigatoriamente ser numerados e enviados em seqncia (isto , no pode ser multiplexado com outros comandos de edio com o mesmo commandTag), com o finalFlag igual a 1, exceto para o ltimo descritor, que deve obrigatoriamente ter o campo finalFlag igual a 0. O privateDataPayload contm os parmetros de comando de edio. Finalmente, o campo FCS contm um checksum de todo o campo privateData, inclusive o privateDataLength.
96
EXEMPLO Eventos de fluxo DSM-CC podem ser usados para transportar descritores de eventos. O protocolo de carrossel de objetos DSM-CC permite a transmisso cclica de objetos de eventos e sistemas de arquivo. Os objetos de eventos so utilizados para mapear nomes de eventos de fluxo em ids de eventos de fluxo, definidos pelos descritores de evento. Os objetos de eventos so utilizados para informar ao Ginga sobre eventos de fluxo DSM-CC que podem ser recebidos. Os nomes dos eventos permitem especificar tipos de eventos, oferecendo maior nvel de abstrao s aplicaes do middleware. Neste caso, convm que o Gerenciador da Base Privada, bem como os objetos de execuo procedural NCL (exemplo, NCLua, NCLet), sejam registrados como observadores dos eventos de fluxo com os quais lidam, utilizando nomes de evento.
Os arquivos de documento NCL e os contedos de objeto de mdia NCL so organizados em estruturas de sistemas de arquivos. Os parmetros de comando de edio, baseados em XML, podem ser diretamente transportados no payload de um descritor de evento ou, alternativamente, organizados em estruturas de sistema de arquivos a serem transportadas no canal de difuso de dados, ou ainda serem recebidas pelo canal de interatividade.
EXEMPLO Um gerador de carrossel DSM-CC poderia ser usado para unir os sistemas de arquivos e os objetos de eventos de fluxo em um fluxo elementar de dados. Quando um comando de edio de documento NCL precisasse ser enviado, um objeto de eventos DSM-CC poderia ser criado, mapeando a string nclEditingCommand em uma id de evento de fluxo, e ento colocado em um carrossel de objetos DSM-CC. Um ou mais descritores de evento de fluxo DSM-CC com a id previamente selecionada poderiam ser ento criados e enviados em outro fluxo elementar MPEG-2 TS. Esses eventos de fluxo poderiam ter sua referncia de tempo colocadas em zero, mas tambm poderiam ser adiados para serem executados em um tempo especfico. O Gerenciador da Base Privada deveria se registrar como um ouvinte nclEditingCommand e seria notificado quando esses eventos de fluxo chegassem.
O commandTag recebido utilizado pelo Gerenciador da Base Privada para interpretar a semntica da command string. Se o command parameter baseado em XML for curto o suficiente, ele pode ser transportado diretamente no payload dos descritores de evento. Se no, o privateDatePayload transporta um conjunto de pares de referncia. No caso de arquivos recebidos pelo canal de difuso (documentos ou ns NCL enviados sem solicitao), cada par relaciona um conjunto de caminhos de arquivos e sua respectiva localizao no sistema de transporte. No caso de arquivos recebidos sob demanda pelo canal de interatividade ou localizados no prprio receptor, nenhum par de referncias necessita ser enviado, exceto o par {uri, null} associado ao documento NCL ou especificao XML do n NCL que dever ser adicionado segundo o comando de adio correspondente. A Tabela 56 mostra as strings de comando e, cercados por parnteses, os parmetros transportados como contedo payload do descritor de evento nclEditingCommand. Os comandos so divididos em trs grupos: o primeiro para operao da base privada (para abrir, ativar, desativar, fechar e salvar bases privadas); o segundo para manipulao de documentos (para adicionar, remover e salvar um documento em uma base privada e para iniciar, pausar, retomar e parar apresentaes de documentos); e a ltima para manipular entidades NCL. Para cada entidade NCL, foram definidos os comandos add e remove. Se uma entidade j existir, o comando add tem a semntica de atualizao (alterao).
NOTA O primeiro grupo de comandos de operao usualmente no vem atravs do canal de difuso de dados. Como j mencionado, comandos de edio podem tambm ser recebidos pelo canal de interatividade ou virem de eventos gerados por objetos imperativos NCLua e NCLet. Comandos de Edio podem tambm ser gerados internamente pelo middleware.
97
0x00
0x05
0x06
0x2E
startDocument (baseId, documentId, interfaceId, offset, refDocumentId, refNodeId) NOTA O parmetro offset especifica um valor de tempo.
0x07
98
Tabela 56 (continuao)
String de comando stopDocument (baseId, documentId) pauseDocument (baseId, documentId) resumeDocument (baseId, documentId) addRegion (baseId, documentId, regionBaseId, regionId, xmlRegion) removeRegion (baseId, documentId, regionId) addRegionBase (baseId, documentId, xmlRegionBase) removeRegionBase (baseId, documentId, regionBaseId) addRule (baseId, documentId, xmlRule) removeRule (baseId, documentId, ruleId) addRuleBase (baseId, documentId, xmlRuleBase) removeRuleBase (baseId, documentId, ruleBaseId) addConnector (baseId, documentId, xmlConnector) removeConnector (baseId, documentId, connectorId) Tag de comando 0x08 Descrio Pra a apresentao de um documento NCL em uma base privada. Todos os eventos do documento que esto em andamento devem obrigatoriamente ser parados Pausa a apresentao de um documento NCL em uma base privada. Todos os eventos do documento que esto em andamento devem obrigatoriamente ser pausados Retoma a apresentao de um documento NCL em uma base privada. Todos os eventos do documento que foram previamente pausados pelo o comando de edio pauseDocument devem obrigatoriamente ser retomados Adiciona um elemento <region> como filho de outro <region> no <regionBase>, ou como filho do <regionBase> (regionId=null) de um documento NCL em uma base privada Remove um elemento <region> de um <regionBase> de um documento NCL em uma base privada Adiciona um elemento <regionBase> ao elemento <head> de um documento NCL em uma base privada. Se a especificao XML do regionBase for enviada em um sistema de transporte como um sistema de arquivo, o parmetro xmlRegionBase apenas uma referncia para esse contedo Remove um elemento <regionBase> do elemento <head> de um documento NCL em uma base privada Adiciona um elemento <rule> ao <ruleBase> de um documento NCL em uma base privada Remove um elemento <rule> do <ruleBase> de um documento NCL em uma base privada Adiciona um elemento <ruleBase> ao elemento <head> de um documento NCL em uma base privada. Se a especificao XML do ruleBase for enviada em um sistema de transporte como um sistema de arquivo, o parmetro xmlRuleBase apenas uma referncia para esse contedo Remove um elemento <ruleBase> do elemento <head> de um documento NCL em uma base privada Adiciona um elemento <connector> ao <connectorBase> de um documento NCL em uma base privada Remove um elemento <connector> do <connectorBase> de um documento NCL em uma base privada Adiciona um elemento <connectorBase> ao elemento <head> de um documento NCL em uma base privada. Se a especificao XML do connectorBase for enviada em um sistema de transporte como um sistema de arquivo, o parmetro xmlConnectorBase apenas uma referncia para esse contedo Remove um elemento <connectorBase> do elemento <head> de um documento NCL em uma base privada Adiciona um elemento <descriptor> ao <descriptorBase> de um documento NCL em uma base privada Remove um elemento <descriptor> do <descriptorBase> de um documento NCL em uma base privada Adiciona um elemento <descriptorSwitch> ao <descriptorBase> de um documento NCL em uma base privada. Se a especificao XML do descriptorSwitch for enviada em um sistema de transporte como um sistema de arquivo, o parmetro xmlDescriptorSwitch apenas uma referncia para esse contedo
0x09
0x0A
0x0B 0x0C
0x0D
0x11
0x15
removeConnectorBase (baseId, documentId, connectorBaseId) addDescriptor (baseId, documentId, xmlDescriptor) removeDescriptor (baseId, documentId, descriptorId)
0x19
99
Tabela 56 (continuao)
String de comando removeDescriptorSwitch (baseId, documentId, descriptorSwitchId) addDescriptorBase (baseId, documentId, xmlDescriptorBase) removeDescriptorBase (baseId, documentId, descriptorBaseId) addTransition (baseId, documentId, xmlTransition) removeTransition (baseId, documentId, transitionId) addTransitionBase (baseId, documentId, xmlTransitionBase) removeTransitionBase (baseId, documentId, transitionBaseId) addImportBase (baseId, documentId, docBaseId, xmlImportBase) removeImportBase (baseId, documentId, docBaseId, documentURI) addImportedDocumentBase (baseId, documentId, xmlImportedDocumentBase) removeImportedDocumentBase (baseId, documentId, importedDocumentBaseId) addImportNCL (baseId, documentId, xmlImportNCL) removeImportNCL (baseId, documentId, documentURI) Tag de comando 0x1A Descrio Remove um elemento <descriptorSwitch> do <descriptorBase> de um documento NCL em uma base privada Adiciona um elemento <descriptorBase> ao elemento <head> de um documento NCL em uma base privada. Se a especificao XML do descriptorBase for enviada em um sistema de transporte como um sistema de arquivo, o parmetro xmlDescriptorBase apenas uma referncia para esse contedo Remove um elemento <descriptorBase> do elemento <head> de um documento NCL em uma base privada Adiciona um elemento <transition> ao <transitionBase> de um documento NCL em uma base privada Remove um elemento <transition> do <transitionBase> de um documento NCL em uma base privada Adiciona um elemento <transitionBase> ao elemento <head> de um documento NCL em uma base privada. Se a especificao XML do transitionBase for enviada em um sistema de transporte como um sistema de arquivo, o parmetro xmlTransitionBase apenas uma referncia para esse contedo Remove um elemento <transitionBase> do elemento <head> de um documento NCL em uma base privada Adiciona um elemento <importBase> base (elemento <regionBase>, <descriptorBase>, <ruleBase>, <transitionBase>, or <connectorBase>) de um documento NCL em uma base privada Remove um elemento <importBase>, cujo atributo documentURI identificado pelo parmetro documentURI, a partir da base (elemento <regionBase>, <descriptorBase>, <ruleBase>, <transitionBase>, or <connectorBase>) de um documento NCL em uma base privada Adiciona um elemento <importedDocumentBase> ao elemento <head> de um documento NCL em uma base privada Remove um elemento <importedDocumentBase> do elemento <head> de um documento NCL em uma base privada Adiciona um elemento <importNCL> ao elemento <importedDocumentBase> de um documento NCL em uma base privada Remove um elemento <importNCL>, cujo atributo documentURI identificado pelo parmetro documentURI, a partir do <importedDocumentBase> de um documento NCL em uma base privada
0x1B
0x1F
0x20
0x21
0x22
0x23
0x24
0x25
0x26
100
Tabela 56 (continuao)
String de comando addNode (baseId, documentId, compositeId, {uri, id}+) Tag de comando 0x27 Descrio Adiciona um n (elemento <media>, <context> ou <switch>) a um n de composio (elemento <body>, <context> ou <switch>) de um documento NCL em uma base privada. A especificao XML do n e seu contedo de mdia podem: a) ser enviados sem solicitao pela rede de difuso de dados; nesse caso, o par {uri, id} usado para relacionar um conjunto de caminhos de arquivos, definidos no documento XML da especificao do n, com suas respectivas localizaes no sistema de transporte (veja exemplos na Seo 12); NOTA Os conjuntos de pares de referncia devem obrigatoriamente ser suficientes para que o middleware possa mapear qualquer referncia a arquivos, presentes na especificao do n, na sua localizao concreta na memria do dispositivo receptor. b) recebidos pelo canal de interatividade sob demanda, ou j ser residentes no receptor; para esses arquivos, nenhum par {uri, id} necessita ser enviado, exceto o par {uri, null} associado especificao XML do n NCL que dever ser adicionado em compositeId, caso o documento XML no seja recebido sem solicitao (pushed file) removeNode(baseId, documentId, compositeId, nodeId) addInterface (baseId, documentId, nodeId, xmlInterface) Remove um n (elemento <media>, <context> ou <switch>) de um n de composio (elemento <body>, <context> ou <switch>) de um documento NCL em uma base privada Adiciona uma interface (<port>, <area>, <property> ou <switchPort>) a um n (elemento <media>, <body>, <context> ou <switch>) de um documento NCL em uma base privada Remove uma interface (<port>, <area>, <property> ou <switchPort>) de um n (elemento <media>, <body>, <context> ou <switch>) de um documento NCL em uma base privada. A interfaceID deve obrigatoriamente identificar um atributo name de um elemento <property> ou um atributo id de um elemento <port>, <area> ou <switchPort> Adiciona um elemento <link> a um n de composio (elemento <body>, <context> ou <switch>) de um documento NCL em uma base privada Remove um elemento <link> de um n de composio (elemento <body>, <context> ou <switch>) de um documento NCL em uma base privada Atribui o valor a uma propriedade. A propertyId deve obrigatoriamente identificar um atributo name de um elemento <property> ou um atributo id de elemento <switchPort>. O <property> ou <switchPort> deve obrigatoriamente pertencer a um n (elemento <body>, <context>, <switch> ou <media>) de um documento NCL em uma base privada identificada pelos parmetros
0x28
0x29
0x2A
addLink (baseId, documentId, compositeId, xmlLink) removeLink (baseId, documentId, compositeId, linkId)
0x2B
0x2C
0x2D
101
Os receptores que somente implementam o perfil NCL DTV Bsico podem no lidar com os seguintes comandos: pauseDocument, resumeDocument, addTransition, removeTransition, addTransitionBase e removeTransitionBase. Ginga associa uma base privada a um canal de televiso. Quando um canal sintonizado, sua base privada correspondente aberta e ativada pelo Gerenciador da Base Privada; outras bases privadas devem ser desativadas. Por razes de segurana, apenas uma nica base privada pode estar ativa por vez. O modo mais simples e restritivo de gerenciar bases privadas ter uma nica base privada aberta por vez. Assim, se o usurio mudar o canal selecionado, recomenda-se que a base privada atual seja fechada. Nesse caso, o comando openBase sempre seguido pelo comando activeBase e o comando deactiveBase nunca usado. Contudo, o nmero de bases privadas que podem ser mantidas em aberto uma deciso de implementao do middleware. Os comandos add tm entidades NCL como seus argumentos (parmetros de comando baseados em XML). Se a entidade especificada j existe ou no, a consistncia do documento deve obrigatoriamente ser mantida pelo formatador NCL, no sentido de que todos os atributos de identidade classificados como obrigatrios devem obrigatoriamente ser definidos. As entidades so definidas utilizando uma notao sinttica idntica quela usada pelos esquemas NCL, com exceo do comando addInterface: o atributo begin de um elemento <area> pode receber o valor now, especificando o NPT atual do nodeId, que deve obrigatoriamente ser o vdeo principal MPEG sendo reproduzido pelo decodificador de hardware. Os identificadores utilizados nos comandos devem obrigatoriamente estar de acordo com a Tabela 57. Tabela 57 Identificadores usados nos comandos de edio Identificadores baseId documentId refDocumentId refNodeId regionId ruleId connectorId descriptorId descriptorSwitchId transitionId regionBaseId ruleBaseId connectorBaseId descriptorBaseId transitionBaseId docBaseId documentURI importedDocumentBaseId compositeID nodeId interfaceId linkId propertyId Definio Identificadores de canal de radiodifuso especificados pelo SBTVD Atributo id de um elemento <ncl> de um documento NCL Atributo id de um elemento <ncl> de um documento NCL Atributo id de um elemento <media> de um documento NCL Atributo id de um elemento <region> de um documento NCL Atributo id de um elemento <rule> de um documento NCL Atributo id de um elemento <connector> de um documento NCL Atributo id de um elemento <descriptor> de um documento NCL Atributo id de um elemento <descriptorSwitch> de um documento NCL Atributo id de um elemento <transition> de um documento NCL Atributo id de um elemento <regionBase> de um documento NCL Atributo id de um elemento <ruleBase> de um documento NCL Atributo id de um elemento <connectorBase> de um documento NCL Atributo id de um elemento <descriptorBase> de um documento NCL Atributo id de um elemento <transitionBase> de um documento NCL Atributo id de um elemento <regionBase>, <ruleBase>, <connectorBase>, <descriptorBase>, ou <transitionBase> de um documento NCL Atributo documentURI de um elemento <importBase> ou um elemento <importNCL> de um documento NCL Atributo id de um elemento <importedDocumentBase> de um documento NCL Atributo id de um elemento <body>, <context> ou <switch> de um documento NCL Atributo id de um elemento <body>, <context>, <switch> ou <media> de um documento NCL Atributo id de um elemento <port>, <area>, <property> ou <switchPort> de um documento NCL Atributo id de um elemento <link> de um documento NCL Atributo id de um elemento <property>, ou <switchPort> de um documento NCL
102
9.2
As entidades NCL utilizadas nos comandos de edio devem obrigatoriamente ser um documento em conformidade com o perfil de Comando NCL 3.0 definido pelo esquema XML a seguir. Convm que os receptores que apenas implementam o perfil Bsico NCL DTV ignorem os elementos e atributos XML relacionados s funcionalidades de Meta-information e Transition Efects. Observar que, diferentemente dos documentos NCL, diversos elementos NCL podem ter o elemento-raiz nos parmetros de comando XML. NCL30EdCommand.xsd
<!-XML Schema for the NCL Language This is NCL Copyright: 2000-2005 PUC-RIO/LABORATORIO TELEMIDIA, All Rights Reserved. See http://www.telemidia.puc-rio.br Public URI: http://www.ncl.org.br/NCL3.0/profiles/NCL30EdCommand.xsd Author: TeleMidia Laboratory Revision: 19/09/2006 --> <schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:animation="http://www.ncl.org.br/NCL3.0/Animation" xmlns:compositeInterface="http://www.ncl.org.br/NCL3.0/CompositeNodeInterface" xmlns:causalConnectorFunctionality="http://www.ncl.org.br/NCL3.0/CausalConnectorFunctionality" xmlns:connectorBase="http://www.ncl.org.br/NCL3.0/ConnectorBase" xmlns:connectorCausalExpression="http://www.ncl.org.br/NCL3.0/ConnectorCausalExpression" xmlns:contentControl="http://www.ncl.org.br/NCL3.0/ContentControl" xmlns:context="http://www.ncl.org.br/NCL3.0/Context" xmlns:descriptor="http://www.ncl.org.br/NCL3.0/Descriptor" xmlns:entityReuse="http://www.ncl.org.br/NCL3.0/EntityReuse" xmlns:extendedEntityReuse="http://www.ncl.org.br/NCL3.0/ExtendedEntityReuse" xmlns:descriptorControl="http://www.ncl.org.br/NCL3.0/DescriptorControl" xmlns:import="http://www.ncl.org.br/NCL3.0/Import" xmlns:keyNavigation="http://www.ncl.org.br/NCL3.0/KeyNavigation" xmlns:layout="http://www.ncl.org.br/NCL3.0/Layout" xmlns:linking="http://www.ncl.org.br/NCL3.0/Linking" xmlns:media="http://www.ncl.org.br/NCL3.0/Media" xmlns:mediaAnchor="http://www.ncl.org.br/NCL3.0/MediaContentAnchor" xmlns:propertyAnchor="http://www.ncl.org.br/NCL3.0/PropertyAnchor" xmlns:structure="http://www.ncl.org.br/NCL3.0/Structure" xmlns:switchInterface="http://www.ncl.org.br/NCL3.0/SwitchInterface" xmlns:testRule="http://www.ncl.org.br/NCL3.0/TestRule" xmlns:testRuleUse="http://www.ncl.org.br/NCL3.0/TestRuleUse" xmlns:timing="http://www.ncl.org.br/NCL3.0/Timing" xmlns:transitionBase="http://www.ncl.org.br/NCL3.0/TransitionBase" xmlns:metainformation="http://www.ncl.org.br/NCL3.0/Metainformation" xmlns:transition="http://www.ncl.org.br/NCL3.0/Transition" xmlns:profile="http://www.ncl.org.br/NCL3.0/EdCommandProfile" targetNamespace="http://www.ncl.org.br/NCL3.0/EdCommandProfile" elementFormDefault="qualified" attributeFormDefault="unqualified" > <!-- import the definitions in the modules namespaces --> <import namespace="http://www.ncl.org.br/NCL3.0/Metainformation" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Metainformation.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Transition" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Transition.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/CausalConnectorFunctionality" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30CausalConnectorFunctionality.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/ConnectorBase"
103
schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30ConnectorBase.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/ConnectorCausalExpression" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30ConnectorCausalExpression.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/ContentControl" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30ContentControl.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Context" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Context.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Descriptor" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Descriptor.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/DescriptorControl" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30DescriptorControl.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/EntityReuse" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30EntityReuse.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/ExtendedEntityReuse" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30ExtendedEntityReuse.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Import" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Import.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/KeyNavigation" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30KeyNavigation.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Layout" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Layout.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Linking" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Linking.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Media" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Media.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/MediaContentAnchor" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30MediaContentAnchor.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/PropertyAnchor" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30PropertyAnchor.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Structure" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Structure.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/SwitchInterface" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30SwitchInterface.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/TestRule" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30TestRule.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/TestRuleUse" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30TestRuleUse.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Timing" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Timing.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/TransitionBase" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30TransitionBase.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Metainformation" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Metainformation.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/Transition" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/NCL30Transition.xsd"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!--EditingCommand --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!--defines the command element --> <!--This is a pseudo-element, only defined to show the elements that may be used in the root of the command parameters XML document--> <!-<complexType name="commandType"> <choice minOccurs="1" maxOccurs="1"> <element ref="profile:ncl"/> <element ref="profile:region"/> <element ref="profile:rule"/> <element ref="profile:connector"/> <element ref="profile:descriptor"/> <element ref="profile:descriptorSwitch"/> <element ref="profile:transition"/> <element ref="profile:regionBase"/>
104
<element ref="profile:ruleBase"/> <element ref="profile:connectorBase"/> <element ref="profile:descriptorBase"/> <element ref="profile:transitionBase"/> <element ref="profile:importBase"/> <element ref="profile:importedDocumentBase"/> <element ref="profile:importNCL"/> <element ref="profile:media"/> <element ref="profile:context"/> <element ref="profile:switch"/> <element ref="profile:port"/> <element ref="profile:area"/> <element ref="profile:property"/> <element ref="profile:switchPort"/> <element ref="profile:link"/> <element ref="profile:meta"/> <element ref="profile:metadata"/> </choice> </complexType> <element name="command" type="profile:commandType"/> --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Structure --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends ncl element --> <element name="ncl" substitutionGroup="structure:ncl"/> <!-- extends head element --> <complexType name="headType"> <complexContent> <extension base="structure:headPrototype"> <sequence> <element ref="profile:importedDocumentBase" minOccurs="0" maxOccurs="1"/> <element ref="profile:ruleBase" minOccurs="0" maxOccurs="1"/> <element ref="profile:transitionBase" minOccurs="0" maxOccurs="1"/> <element ref="profile:regionBase" minOccurs="0" maxOccurs="unbounded"/> <element ref="profile:descriptorBase" minOccurs="0" maxOccurs="1"/> <element ref="profile:connectorBase" minOccurs="0" maxOccurs="1"/> <element ref="profile:meta" minOccurs="0" maxOccurs="unbounded"/> <element ref="profile:metadata" minOccurs="0" maxOccurs="unbounded"/> </sequence> </extension> </complexContent> </complexType> <element name="head" type="profile:headType" substitutionGroup="structure:head"/> <!-- extends body element --> <complexType name="bodyType"> <complexContent> <extension base="structure:bodyPrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <group ref="profile:contextInterfaceElementGroup"/> <element ref="profile:media"/> <element ref="profile:context"/> <element ref="profile:switch"/> <element ref="profile:link"/> <element ref="profile:meta"/> <element ref="profile:metadata"/> </choice> </extension>
105
</complexContent> </complexType> <element name="body" type="profile:bodyType" substitutionGroup="structure:body"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Layout --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends regionBase element --> <complexType name="regionBaseType"> <complexContent> <extension base="layout:regionBasePrototype"> <choice minOccurs="1" maxOccurs="unbounded"> <element ref="profile:region"/> <element ref="profile:importBase"/> </choice> </extension> </complexContent> </complexType> <complexType name="regionType"> <complexContent> <extension base="layout:regionPrototype"> </extension> </complexContent> </complexType> <element name="regionBase" type="profile:regionBaseType" substitutionGroup="layout:regionBase"/> <element name="region" type="profile:regionType" substitutionGroup="layout:region"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Media --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends Media elements --> <!-- media interface element groups --> <group name="mediaInterfaceElementGroup"> <choice> <element ref="profile:area"/> <element ref="profile:property"/> </choice> </group> <complexType name="mediaType"> <complexContent> <extension base="media:mediaPrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <group ref="profile:mediaInterfaceElementGroup"/> </choice> <attributeGroup ref="descriptor:descriptorAttrs"/> <attributeGroup ref="entityReuse:entityReuseAttrs"/> <attributeGroup ref="extendedEntityReuse:extendedEntityReuseAttrs"/> </extension> </complexContent> </complexType> <element name="media" type="profile:mediaType" substitutionGroup="media:media"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Context --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends context element --> <!-- composite node interface element groups -->
106
<group name="contextInterfaceElementGroup"> <choice> <element ref="profile:port"/> <element ref="profile:property"/> </choice> </group> <complexType name="contextType"> <complexContent> <extension base="context:contextPrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <group ref="profile:contextInterfaceElementGroup"/> <element ref="profile:media"/> <element ref="profile:context"/> <element ref="profile:link"/> <element ref="profile:switch"/> <element ref="profile:meta"/> <element ref="profile:metadata"/> </choice> <attributeGroup ref="entityReuse:entityReuseAttrs"/> </extension> </complexContent> </complexType> <element name="context" type="profile:contextType" substitutionGroup="context:context"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- MediaContentAnchor --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends area element --> <complexType name="componentAnchorType"> <complexContent> <extension base="mediaAnchor:componentAnchorPrototype"> <attribute name="now" type="string" use="optional"/> </extension> </complexContent> </complexType> <element name="area" type="profile:componentAnchorType" substitutionGroup="mediaAnchor:area"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- CompositeNodeInterface --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends port element --> <complexType name="compositeNodePortType"> <complexContent> <extension base="compositeInterface:compositeNodePortPrototype"> </extension> </complexContent> </complexType> <element name="port" type="profile:compositeNodePortType" substitutionGroup="compositeInterface:port"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- PropertyAnchor --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends property element --> <complexType name="propertyAnchorType"> <complexContent> <extension base="propertyAnchor:propertyAnchorPrototype"> </extension> </complexContent>
107
</complexType> <element name="property" type="profile:propertyAnchorType" substitutionGroup="propertyAnchor:property"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- SwitchInterface --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends switchPort element --> <complexType name="switchPortType"> <complexContent> <extension base="switchInterface:switchPortPrototype"> </extension> </complexContent> </complexType> <element name="mapping" substitutionGroup="switchInterface:mapping"/> <element name="switchPort" type="profile:switchPortType" substitutionGroup="switchInterface:switchPort"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Descriptor --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- substitutes descriptorParam element --> <element name="descriptorParam" substitutionGroup="descriptor:descriptorParam"/> <!-- extends descriptor element --> <complexType name="descriptorType"> <complexContent> <extension base="descriptor:descriptorPrototype"> <attributeGroup ref="layout:regionAttrs"/> <attributeGroup ref="timing:explicitDurAttrs"/> <attributeGroup ref="timing:freezeAttrs"/> <attributeGroup ref="keyNavigation:keyNavigationAttrs"/> <attributeGroup ref="transition:transAttrs"/> </extension> </complexContent> </complexType> <element name="descriptor" type="profile:descriptorType" substitutionGroup="descriptor:descriptor"/> <!-- extends descriptorBase element --> <complexType name="descriptorBaseType"> <complexContent> <extension base="descriptor:descriptorBasePrototype"> <choice minOccurs="1" maxOccurs="unbounded"> <element ref="profile:importBase"/> <element ref="profile:descriptor"/> <element ref="profile:descriptorSwitch"/> </choice> </extension> </complexContent> </complexType> <element name="descriptorBase" type="profile:descriptorBaseType" substitutionGroup="descriptor:descriptorBase"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Linking --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- substitutes linkParam and bindParam elements --> <element name="linkParam" substitutionGroup="linking:linkParam"/>
108
<element name="bindParam" substitutionGroup="linking:bindParam"/> <!-- extends bind element and link element, as a consequence--> <complexType name="bindType"> <complexContent> <extension base="linking:bindPrototype"> <attributeGroup ref="descriptor:descriptorAttrs"/> </extension> </complexContent> </complexType> <element name="bind" type="profile:bindType" substitutionGroup="linking:bind"/> <!-- extends link element --> <complexType name="linkType"> <complexContent> <extension base="linking:linkPrototype"> </extension> </complexContent> </complexType> <element name="link" type="profile:linkType" substitutionGroup="linking:link"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Connector --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends connectorBase element --> <complexType name="connectorBaseType"> <complexContent> <extension base="connectorBase:connectorBasePrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <element ref="profile:importBase"/> <element ref="profile:causalConnector" /> </choice> </extension> </complexContent> </complexType> <complexType name="simpleActionType"> <complexContent> <extension base="connectorCausalExpression:simpleActionPrototype"> <attributeGroup ref="animation:animationAttrs"/> </extension> </complexContent> </complexType> <element name="connectorBase" type="profile:connectorBaseType" substitutionGroup="connectorBase:connectorBase"/> <element name="causalConnector" substitutionGroup="causalConnectorFunctionality:causalConnector"/> <element name="connectorParam" substitutionGroup="causalConnectorFunctionality:connectorParam"/> <element name="simpleCondition" substitutionGroup="causalConnectorFunctionality:simpleCondition"/> <element name="compoundCondition" substitutionGroup="causalConnectorFunctionality:compoundCondition"/> <element name="simpleAction" type="profile:simpleActionType" substitutionGroup="causalConnectorFunctionality:simpleAction"/> <element name="compoundAction" substitutionGroup="causalConnectorFunctionality:compoundAction"/> <element name="assessmentStatement" substitutionGroup="causalConnectorFunctionality:assessmentStatement"/>
109
<element name="attributeAssessment" substitutionGroup="causalConnectorFunctionality:attributeAssessment"/> <element name="valueAssessment" substitutionGroup="causalConnectorFunctionality:valueAssessment"/> <element name="compoundStatement" substitutionGroup="causalConnectorFunctionality:compoundStatement"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- TestRule --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends rule element --> <complexType name="ruleType"> <complexContent> <extension base="testRule:rulePrototype"> </extension> </complexContent> </complexType> <element name="rule" type="profile:ruleType" substitutionGroup="testRule:rule"/> <!-- extends compositeRule element --> <complexType name="compositeRuleType"> <complexContent> <extension base="testRule:compositeRulePrototype"> </extension> </complexContent> </complexType> <element name="compositeRule" type="profile:compositeRuleType" substitutionGroup="testRule:compositeRule"/> <!-- extends ruleBase element --> <complexType name="ruleBaseType"> <complexContent> <extension base="testRule:ruleBasePrototype"> <choice minOccurs="1" maxOccurs="unbounded"> <element ref="profile:importBase"/> <element ref="profile:rule"/> <element ref="profile:compositeRule"/> </choice> </extension> </complexContent> </complexType> <element name="ruleBase" type="profile:ruleBaseType" substitutionGroup="testRule:ruleBase"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- TestRuleUse --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends bindRule element --> <complexType name="bindRuleType"> <complexContent> <extension base="testRuleUse:bindRulePrototype"> </extension> </complexContent> </complexType> <element name="bindRule" type="profile:bindRuleType" substitutionGroup="testRuleUse:bindRule"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- ContentControl --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends switch element --> <!-- switch interface element groups --> <group name="switchInterfaceElementGroup"> <choice>
110
<element ref="profile:switchPort"/> </choice> </group> <!-- extends defaultComponent element --> <complexType name="defaultComponentType"> <complexContent> <extension base="contentControl:defaultComponentPrototype"> </extension> </complexContent> </complexType> <element name="defaultComponent" type="profile:defaultComponentType" substitutionGroup="contentControl:defaultComponent"/> <complexType name="switchType"> <complexContent> <extension base="contentControl:switchPrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <group ref="profile:switchInterfaceElementGroup"/> <element ref="profile:bindRule"/> <element ref="profile:switch"/> <element ref="profile:media"/> <element ref="profile:context"/> </choice> <attributeGroup ref="entityReuse:entityReuseAttrs"/> </extension> </complexContent> </complexType> <element name="switch" type="profile:switchType" substitutionGroup="contentControl:switch"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- DescriptorControl --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends defaultDescriptor element --> <complexType name="defaultDescriptorType"> <complexContent> <extension base="descriptorControl:defaultDescriptorPrototype"> </extension> </complexContent> </complexType> <element name="defaultDescriptor" type="profile:defaultDescriptorType" substitutionGroup="descriptorControl:defaultDescriptor"/> <!-- extends descriptorSwitch element --> <complexType name="descriptorSwitchType"> <complexContent> <extension base="descriptorControl:descriptorSwitchPrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <element ref="profile:descriptor"/> <element ref="profile:bindRule"/> </choice> </extension> </complexContent> </complexType> <element name="descriptorSwitch" type="profile:descriptorSwitchType" substitutionGroup="descriptorControl:descriptorSwitch"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Timing -->
111
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Import --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <complexType name="importBaseType"> <complexContent> <extension base="import:importBasePrototype"> </extension> </complexContent> </complexType> <complexType name="importNCLType"> <complexContent> <extension base="import:importNCLPrototype"> </extension> </complexContent> </complexType> <complexType name="importedDocumentBaseType"> <complexContent> <extension base="import:importedDocumentBasePrototype"> </extension> </complexContent> </complexType> <element name="importBase" type="profile:importBaseType" substitutionGroup="import:importBase"/> <element name="importNCL" type="profile:importNCLType" substitutionGroup="import:importNCL"/> <element name="importedDocumentBase" type="profile:importedDocumentBaseType" substitutionGroup="import:importedDocumentBase"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- EntityReuse --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- ExtendedEntityReuse --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- KeyNavigation --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- TransitionBase --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- extends transitionBase element --> <complexType name="transitionBaseType"> <complexContent> <extension base="transitionBase:transitionBasePrototype"> <choice minOccurs="0" maxOccurs="unbounded"> <element ref="profile:transition"/> <element ref="profile:importBase"/> </choice> </extension> </complexContent> </complexType> <element name="transitionBase" type="profile:transitionBaseType" substitutionGroup="transitionBase:transitionBase"/>
112
<!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Transition --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <element name="transition" substitutionGroup="transition:transition"/> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <!-- Metainformation --> <!-- = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = --> <element name="meta" substitutionGroup="metainformation:meta"/> <element name="metadata" substitutionGroup="metainformation:metadata"/> </schema>
113
Como com todos os exibidores de objetos de mdia, um exibidor Lua, uma vez instanciado, deve executar os procedimentos de iniciao do objeto NCL que controlar. Porm, diferentemente dos outros exibidores de mdia, o cdigo de iniciao deve tambm ser especificado pelo autor do objeto NCLua. Os procedimentos de iniciao so executados apenas uma vez, para cada instncia, e criam funes e objetos que podem ser usados durante a execuo do objeto NCLua e, em particular, registram um ou mais tratadores de eventos para a comunicao com o formatador NCL. Depois da iniciao, a execuo do objeto NCLua torna-se orientada a evento, em ambas as direes. Isto , qualquer ao comandada pelo formatador NCL dirigida aos tratadores de evento registrados e qualquer notificao de mudana de estado de eventos NCL enviada como um evento ao formatador NCL (como, por exemplo, o fim da execuo do cdigo procedural). O exibidor Lua estar ento pronto para executar qualquer intruo de start ou set (ver 8.5).
A definio de cada funo nos mdulos mencionados respeita a seguinte nomenclatura: funcname (parnameI: partypeI [; optnameI: opttypeI]) -> retname: rettype 10.3.2 Mdulo canvas 10.3.2.1 Objeto canvas
Quando um objeto de mdia NCLua iniciado, a regio do elemento <media> correspondente (do tipo application/x-ginga-NCLua) fica disponvel como a varivel global canvas para o script Lua. Se o elemento de <media> no tiver nenhuma regio especificada (propriedades left, right, top and bottom), ento o valor para canvas deve ser estabelido como nil. Exemplificando: para uma regio definida em um documento NCL como: <region id="luaRegion" width="300" height="100" top="200" left="20"/> A varivel 'canvas' em um objeto de mdia associado regio luaRegion ligada a um objeto canvas de tamanho 300x100, associada com a regio (20,200). Um canvas oferece uma API grfica para ser usada por aplicaes NCLua. Atravs dela possvel desenhar linhas, retngulos, fontes, imagens etc. Um canvas guarda em seu estado atributos sob os quais as primitivas de desenho operam, por exemplo, se seu atributo de cor for azul, uma chamada a canvas:drawLine() desenha uma linha azul no canvas. As coordenadas passadas so sempre relativas ao ponto mais esquerda e ao topo do canvas (0,0).
114
10.3.2.2
Construtores
Atravs de qualquer canvas possvel criar novos canvas e combin-los atravs de operaes de composio.
canvas:new (image_path: string) -> canvas: object Argumentos image_path Valor de retorno canvas Descrio Retorna um novo canvas cujo contedo a imagem recebida como parmetro. O novo canvas deve obrigatoriamente manter os aspectos de transparncia da imagem original. canvas:new (width, height: number) -> canvas: object Argumentos width height Valores de retorno canvas Descrio Retorna um novo canvas com o tamanho recebido. Inicialmente todos os pixels devem ser transparentes, obrigatoriamente. 10.3.2.3 Atributos Novo canvas Largura do canvas Altura do canvas Canvas representando a imagem Caminho da imagem
Todos os mtodos de atributos possuem o prefixo attr e servem tanto para ler quanto para alterar um atributo (com algumas excees). Quando o mtodo chamado sem parmetros de entrada o valor corrente do atributo retornado, em contra-partida, quando chamado com parmetros, esses devem ser os novos valores do atributo.
115
canvas:attrSize () -> width, height: number Argumentos Valores de retorno width height Descrio Retorna as dimenses do canvas. importante observar que no permitido alterar as dimenses de um canvas. canvas:attrColor (R, G, B, A: number) Argumentos R G B A Descrio Altera a cor do canvas. As cores so passadas em RGBA, onde A varia de 0 (totalmente transparente) a 255 (totalmente opaco). As primitivas (ver 10.3.3.4) so desenhadas com a cor desse atributo do canvas. O valor inicial 0,0,0,255 (preto). Componente vermelha da cor Componente verde da cor Componente azul da cor Componente alpha da cor Largura do canvas Altura do canvas
canvas:attrColor (clr_name: string) Argumentos clr_name Altera a cor do canvas. As cores so passadas atravs de uma string correspondendo a uma das 16 cores NCL predefinidas: 'white', 'aqua', 'lime', 'yellow', 'red', 'fuchsia', 'purple', 'maroon', 'blue', 'navy', 'teal', 'green', 'olive', 'silver', 'gray', 'black' Para valores em string, o alpha opaco (correspondendo a A = 255). As primitivas (ver 10.3.3.4) so desenhadas com a cor desse atributo do canvas. O valor inicial 'black'. Nome da cor
116
canvas:attrColor () -> R, G, B, A: number Valores de retorno R G B A Descrio Retorna a cor do canvas. canvas:attrFont (face: string; size: number; style: string) Argumentos face size style Descrio Altera a fonte do canvas. As seguintes fontes devem obrigatoriamente estar disponveis: 'Tiresias, Verdana. O tamanho em pixels e representa a altura mxima de uma linha escrita com a fonte escolhida. Os estilos possveis so: 'bold', 'italic' ou 'bold-italic'. O valor nil assume que nenhum dos estilos ser usado. Qualquer valor passado no suportado deve obrigatoriamente gerar um erro. O valor inicial da fonte indeterminado. Nome da fonte Tamanho da fonte Estilo da fonte Componente vermelha da cor Componente verde da cor Componente azul da cor Componente alpha da cor
canvas:attrFont () -> face: string; size: number; style: string Valores de retorno face size style Descrio Retorna a fonte do canvas. Nome da fonte Tamanho da fonte Estilo da fonte
117
canvas:attrClip (x, y, width, height: number) Argumentos x y width height Descrio Altera a rea de clipping do canvas. As primitivas de desenho (ver 10.3.3.4) e o mtodo canvas:compose() s operam dentro desta regio de clipping. O valor inicial o canvas inteiro. canvas:attrClip () -> x, y, width, height: number Valores de retorno x y width height Descrio Retorna a rea de clipping do canvas. Coordenada da rea de clipping Coordenada da rea de clipping Largura da rea de clipping Altura da rea de clipping Coordenada da rea de clipping Coordenada da rea de clipping Largura da rea de clipping Altura da rea de clipping
canvas:attrCrop (x, y, w, h: number) Argumentos x y w h Descrio Altera a regio de crop do canvas. Apenas a regio configurada passa a ser usada em operaes de composio. O valor inicial o canvas inteiro. O canvas principal no pode ter seu valor alterado, pois controlado pelo formatador NCL. Coordenada da regio de crop Coordenada da regio de crop Largura da regio de crop Altura da regio de crop
118
canvas:attrCrop () -> x, y, w, h: number Valores de retorno x y w h Descrio Retorna a regio de crop do canvas. Coordenada da regio de crop Coordenada da regio de crop Largura da regio de crop Altura da regio de crop
canvas:attrFlip (horiz, vert: boolean) Argumentos horiz vert Descrio Configura o espelhamento do canvas usado em funes de composio. O canvas principal no pode ter seu valor alterado, pois controlado pelo formatador NCL. Se o espelhamento for horizontal Se o espelhamento for vertical
canvas:attrFlip () -> horiz, vert: boolean Valores de retorno horiz vert Descrio Retorna a configurao de espelhamento do canvas. Se o espelhamento for horizontal Se o espelhamento for vertical
119
canvas:attrOpacity (opacity: number) Argumento opacity Descrio Altera a opacidade do canvas. O valor da opacidade varia entre 0 (transparente) e 255 (opaco). O canvas principal no pode ter seu valor alterado, pois controlado pelo formatador NCL. Novo valor de opacidade do canvas
canvas:attrOpacity () -> opacity: number Valor de retorno opacity Descrio Retorna o valor da opacidade do canvas. Opacidade do canvas
canvas:attrRotation (degrees: number) Argumento degrees Descrio Configura o atributo de rotao do canvas, que deve ser mltiplo de 90 graus. O canvas principal no pode ter seu valor alterado, pois controlado pelo formatador NCL. Rotao do canvas em graus
canvas:attrRotation () -> degrees: number Valor de retorno degrees Descrio Retorna o atributo de rotao do canvas. Rotao do canvas em graus
120
canvas:attrScale (w, h: number) Argumentos w h Descrio Escalona o canvas com nova largura e altura. Um dos valores pode ser true, indicando que a proporo do canvas deve ser mantida. O atributo de escalonamento independente do atributo de tamanho, ou seja, o tamanho do canvas mantido. O canvas principal no pode ter seu valor alterado, pois controlado pelo formatador NCL. Largura de escalonamento do canvas Altura de escalonamento do canvas
canvas:attrScale () -> w, h: number Valor de retorno w h Descrio Retorna os valores de escalonamento do canvas. 10.3.2.4 Primitivas Largura de escalonamento do canvas Altura de escalonamento do canvas
Todos os mtodos a seguir levam em considerao os atributos do canvas. canvas:drawLine (x1, y1, x2, y2: number) Argumentos x1 y1 x2 y2 Descrio Desenha uma linha com suas extremidades em (x1,y1) e (x2,y2). Extremidade 1 da linha Extremidade 1 da linha Extremidade 2 da linha Extremidade 2 da linha
121
canvas:drawRect (mode: string; x, y, width, height: number) Argumentos mode x y width height Descrio Funo para desenho e preenchimento de retngulos. O parmetro mode pode receber 'frame' para desenhar apenas a moldura do retngulo ou 'fill' para preench-lo. Modo de desenho Coordenada do retngulo Coordenada do retngulo Largura do retngulo Altura do retngulo
canvas:drawRoundRect (mode: string; x, y, width, height, arcWidth, arcHeight: number) Argumentos mode x y width height arcWidth arcHeight Descrio Funo para desenho e preenchimento de retngulos arredondados. O parmetro mode pode receber 'frame' para desenhar apenas a moldura do retngulo ou 'fill' para preench-lo. Modo de desenho Coordenada do retngulo Coordenada do retngulo Largura do retngulo Altura do retngulo Largura do arco do canto arredondado Altura do arco do canto arredondado
122
canvas:drawPolygon (mode: string) -> drawer: function Argumentos mode Valores de retorno f Descrio Mtodo para desenho e preenchimento de polgonos. O parmetro mode recebe o valor 'open', para desenhar o polgono sem ligar o ltimo ponto ao primeiro; 'close', para desenhar o polgono ligando o ltimo ponto ao primeiro; or 'fill', para desenhar o polgono ligando o ltimo ponto ao primeiro e colorir a regio interior. A funo canvas:drawPolygon retorna uma funo annima "drawer" com a assinatura: function (x, y) end A funo retornada recebe as coordenadas do prximo vrtice do polgono e retorna a si mesmo com resultado. Esse procedimento recorrente facilita a composio: canvas:drawPolygon('fill')(1,1)(10,1)(10,10)(1,10)() Ao receber nil a funo "drawer" efetua a operao encadeada. Qualquer chamada subsequente deve obrigatoriamente gerar um erro. Funo de desenho Modo de desenho
canvas:drawEllipse (mode: string; xc, yc, width, height, ang_start, ang_end: number) Argumentos mode xc yc width height ang_start ang_end Descrio Desenha elipses e outras primitivas similares tais como crculos, arcos e setores. O parmetro mode pode receber 'arc' para desenhar apenas a circunferncia ou 'fill' para preenchimento interno. Modo de desenho Centro da elipse Centro da elipse Largura da elipse Altura da elipse ngulo de incio ngulo de fim
123
canvas:drawText (x,y: number; text: string) Argumentos x y text Descrio Desenha o texto passado na posio (x,y) do canvas utilizando a fonte configurada em canvas:attrFont(). 10.3.2.5 Miscelnea Coordenada do texto Coordenada do texto Texto a ser desenhado
canvas:clear ([x, y, w, h: number]) Argumentos x y w h Descrio Limpa o canvas com a cor configurada em attrColor. Caso no sejam passados os parmetros de rea, assume-se que o canvas inteiro ser limpo. Coordenada da rea de clear Coordenada da rea de clear Largura da rea de clear Altura da rea de clear
canvas:flush () Descrio Atualiza o canvas aps operaes de desenho e de composio. suficiente cham-lo apenas uma vez aps uma seqncia de operaes. canvas:compose (x, y: number; src: canvas; [ src_x, src_y, src_width, src_height: number ]) Argumentos x y src src_x src_y src_width Posio da composio Posio da composio Canvas a ser composto Posio da composio no canvas src Posio da composio no canvas src Largura da composio no canvas src
124
src_height Descrio
Faz sobre o canvas (canvas de destino), em sua posio (x,y), a composio pixel a pixel com src (canvas de origem). Os outros parmetros so opcionais e indicam que parte do canvas src compor. Quando ausentes, o canvas inteiro composto. Essa operao chama src:flush() automaticamente antes da composio. A composio satisfaz a equao: Cd = Cs*As + Cd*(255 - As)/255 Ad = As*As + Ad*(255 - As)/255 onde: Cd = cor do canvas de destino (canvas) Ad = alfa do canvas de destino (canvas) Cs = cor do canvas de origem (src) As = alfa do canvas de origem (src) Aps a operao o canvas de destino possui o resultado da composio e src no sofre qualquer alterao. canvas:pixel (x, y, R, G, B, A: number) Argumentos x y R G B A Descrio Altera a cor de um pixel do canvas. Posio do pixel Posio do pixel Componente vermelha da cor Componente verde da cor Componente azul da cor Componente alpha da cor
125
canvas:pixel (x, y: number) -> R, G, B, A: number Argumentos x y Valores de retorno R G B A Descrio Retorna a cor de um pixel do canvas. canvas:measureText (text: string) -> dx, dy: number Argumentos text Valores de retorno dx dy Descrio Retorna as coordenadas limtrofes para o texto passado, caso ele seja desenhado na posio (x,y) do canvas com a fonte configurada em canvas:attrFont(). 10.3.3 Mdulo event 10.3.3.1 Viso geral Largura do texto Altura do texto Texto a ser medido Componente vermelha da cor Componente verde da cor Componente azul da cor Componente alpha da cor Posio do pixel Posio do pixel
Este mdulo oferece uma API para tratamento de eventos. Atravs dele o formatador NCL e uma aplicao NCLua podem se comunicar de maneira assncrona. Uma aplicao tambm pode usufruir desse mecanismo internamente, atravs de eventos da classe "user". Provavelmente o uso mais comum de aplicaes NCLua ser tratando eventos: sejam eles eventos NCL (ver 7.2.8) ou de interao com o usurio (pelo controle remoto, por exemplo). Durante sua iniciao, antes de se tornar orientado a eventos, um script Lua deve obrigatoriamente registrar uma funo de tratamento de eventos. Aps a iniciao, qualquer ao tomada pela aplicao somente em resposta a um evento enviado pelo formatador NCL funo "handler". === example.lua === ... -- cdigo de iniciao
126
... end
-- cdigo tratador
event.register(handler) -- registro do tratador no middleware === fim === Entre os tipos de eventos que podem chegar ao handler esto todos os eventos gerados pelo formatador NCL. Um script Lua tambm capaz de gerar eventos, ditos "espontneos", com uma chamada funo event.post(evt). 10.3.3.2 Funes
event.post ([dst: string]; evt: event) -> sent: boolean; err_msg: string Argumentos dst evt Valores de retorno sent err_msg Descrio Posta o evento passado. O parmetro "dst" o destinatrio do evento e pode assumir os valores "in" (envio para a prpria aplicao) e "out" (envio para o formatador NCL). O valor default out. Se o evento for enviado com sucesso Mensagem de erro em caso de falha Destinatrio do evento Evento a ser postado
event.timer (time: number, f: function) -> cancel: function Argumentos time f Valor de retorno unreg Descrio Cria um timer que expira aps time (em milissegundos) e ento chama a funo f. A assinatura de f simples, sem recebimento de parmetros: function f () end O valor de 0 milissegundos vlido. Nesse caso, event.timer() deve, obrigatoriamente, retornar imediatamente e f deve ser chamada assim que possvel. Funo para cancelar o timer Tempo em milissegundos Funo de callback
127
event.register ([pos: number]; f: function; [class: string]; [: any]) Argumentos pos f class Descrio Registra a funo passada como um listener de eventos, isto , sempre que ocorrer um evento, f ser chamada. A funo f , assim, a funo de tratamento de eventos (function handler). O parmetro pos opcional e indica a posio em que f registrada. Caso no seja passado, a funo registrada em ltimo lugar. O parmetro class tambm opcional e quando passado indica que classe de eventos a funo deve receber. Se o parmentro for especificado, outros filtros dependentes da classe podem ser definidos. O valor nil em qualquer posio indica que o parmetro no deve ser filtrado. A assinatura de f : function f (evt) end -> handled: boolean Onde evt o evento que, ao ocorrer, ativa a funo. A funo pode retornar true, para sinalizar que o evento foi tratado e, portanto, no deve ser enviado a outros tratadores. recomendado que a funo, definida pela aplicao, retorne rapidamente, j que, enquanto ela estiver executando, nenhum outro evento ser processado. O formatador NCL deve obrigatoriamente garantir que as funes recebam os eventos na ordem em que foram registradas, e se nenhuma delas retornar o valor true, o formatador NCL deve notificar os outros tratadores registrados. Posio do registro (opcional) Funo de callback. Filtro de classe (opcional) Filtro dependente da classe (opcional)
event.unregister (f: function) Argumentos f Descrio Tira do registro a funo passada como um listener, isto , novos eventos no sero mais passados a f. Funo de callback
128
event.uptime () -> ms: number Valores de retorno ms Descrio Retorna o nmero de milissegundos decorridos desde o incio da aplicao. 10.3.3.3 Classes de eventos Tempo em milissegundos
A funo event.post() e o handler registrado em event.register() recebem eventos como parmetros. Um evento descrito por uma tabela Lua normal, onde o campo class obrigatrio e identifica a classe do evento. As seguintes classes de eventos so definidas: Classe key: evt = { class='key', type: string, key: string} * type pode ser 'press' ou 'release'. * key o valor da tecla em questo.
EXEMPLO NOTA evt = { class='key', type='press', key=0}
Na classe key, o filtro dependente da classe pode ser type e key, nessa ordem.
Classe ncl: As relaes entre os ns de mdia NCL so baseadas em eventos. Lua tem acesso a esses eventos atravs da Classe ncl. Os eventos podem agir nas duas direes, isto , o formatador pode enviar eventos de ao para mudar o estado do exibidor Lua, e este, por sua vez, pode disparar eventos de transio para indicar mudanas de estado. Nos eventos, o campo type deve obrigatoriamente assumir um dos trs valores: 'presentation', 'selection' ou 'attribution' Eventos podem ser direcionados a ncoras especficas ou ao n como um todo, isto identificado no campo area, que assume o n inteiro, quando ausente. No caso de um evento gerado pelo formatador, o campo action deve obrigatoriamente ter um dos valores: 'start', 'stop', 'abort', 'pause' ou 'resume' Tipo presentation: evt = { class='ncl', type='presentation', label='?', action=?} Tipo attribution:
129
evt = { class='ncl', type='attribution', name='?', action=?', value='?' } Para eventos gerados pelo exibidor Lua, o campo "action" dever obrigatoriamente assumir um dos valores 'start', 'stop', 'abort', 'pause' ou 'resume' Tipo presentation: evt = { class='ncl', type='presentation', label='?', action=start/stop/abort/pause/resume}} Tipo selection: evt = { class='ncl', type='selection', label='?', action='stop' } Tipo attribution: evt = { class='ncl', type='attribution', name='?', action='start'/'stop'/'abort'/'pause'/'resume', value='?' }
NOTA Na classe ncl, o filtro dependente da classe pode ser type, area e action, nessa ordem.
Classe edit: Esta classe espelha os comandos de edio para o Gerenciador de Bases Privadas (ver Seo 9). Entretanto, h uma diferena entre os comandos de edio provenientes dos eventos de fluxo DSM-CC e os comandos de edio realizados pelos scripts Lua (objetos NCLua). Os primeiros alteram no somente a apresentao de um documento NCL, mas tambm a especificao de um documento NCL. Ou seja, no final do processo um novo documento NCL gerado, incorporando todos os resultados da edio. Por outro lado, os comandos de edio provenientes dos objetos de mdia NCLua alteram somente a apresentao do documento NCL. O documento original preservado durante todo o processo de edio.
Assim como nas outras classes de evento, um comando de edio representado por uma tabela Lua. Todo evento deve obrigatoriamente carregar o campo command: uma string com o nome do comando de edio. Os outros campos dependem do tipo de comando, conforme Tabela 56 na Seo 9. A nica diferena com relao ao campo que define os pares de referncia {uri,id}, denominado data na classe edit. O valor do campo aceita no apenas os pares de referncia {uri,id} mencionados na Tabela 56, como tambm strings XML com o contedo a ser adicionado.
EXEMPLO
evt = { command = addNode, compositeId = someId, data = <media>..., } Os campos baseId e documentId (quando aplicveis) so opcionais e assumem por default o identificador da base e do documento no qual o NCLua est executando.
130
O evento descrevendo o comando de edio tambm pode receber uma referncia de tempo como parmetro opcional time. Esse parmetro opcional pode ser usado para especificar o exato momento em que o comando de edio deve ser executado. Se este parmetro no for fornecido na chamada de funo, o comando de edio deve ser executado imediatamente. Quando fornecido, o parmetro pode ter dois tipos diferentes de valores, com diferentes significados. Se for um valor numrico, define a quantidade de tempo, em segundos, que a execuo do comando deve ser postergada. Contudo, esse parmetro tambm pode especificar o exato momento para execuo do comando, em valores absolutos. Para isso, o parmetro deve obrigatoriamente ser uma tabela com os seguintes campos: year (quatro dgitos), month (1 a 12), day (1 a 31), hour (0 a 23), minute (0 a 59), second (0 a 61) e isdst (sinalizador de horrio de vero, um booleano). Classe tcp: O uso do canal de interatividade realizado por meio desta classe de eventos. Para o envio ou recebimento de dados tcp, uma conexo deve obrigatoriamente ser estabelecida inicialmente, postando um evento na forma: evt = { class='tcp', type='connect', host=addr, port=number, [timeout=number] } O resultado da conexo retornado em um tratador de eventos pr-registrado para a classe. O evento retornado tem a seguinte forma: evt = { class='tcp', type='connect', host=addr, port=number, connection=identifier, error=<err_msg>} Os campos error e connection so mutuamente exclusivos. Quando houver um erro de comunicao, uma mensagem deve ser retornada no campo error. Quando houver sucesso na comunicao, o identificador da conexo retornado no campo connection. Uma aplicao NCLua envia dados por um canal de interatividade, postando eventos na forma: evt = { class=tcp, type='data', connection=identifier, value=string, [timeout=number] } De forma similar, uma aplicao NCLua recebe dados transportados por um canal de interatividade fazendo uso de eventos na forma: evt = { class=tcp, type='data', connection=identifier, value=string, error=msg } Os campos error e value so mutuamente exclusivos. Quando h um erro de comunicao, uma mensagem retornada pelo campo error. Quando a comunicao bem-sucedida, a mensagem transportada passada no campo value. Para fechar uma conexo, o seguinte evento deve obrigatoriamente ser postado: evt = { class='tcp', type='disconnect', connection=identifier }
NOTA 1 NOTA 2 Recomenda-se que questes como autenticao, sejam tratadas em uma implementao especfica do middleware. Na classe tcp, o filtro dependente da classe s pode ser connection.
Class sms: O compartamento de envio e recebimento por meio de SMS muito semelhante ao definido na classe tcp. Tambm como aquela classe, a classe sms opcional no caso da implementao Ginga para receptores full-seg. Uma aplicao NCLua envia dados por SMS, postando eventos na forma: evt = { class=sms, to=phone number, value=string }
131
De forma similar, uma aplicao NCLua recebe dados transportados por SMS, fazendo uso de eventos na forma: evt = { class=sms, from=phone number, value=string }
NOTA 1 Recomenda-se que questes como autenticao etc. sejam tratadas em uma implementao especfica do middleware. NOTA 2 Na classe sms, o filtro dependente da classe s pode ser from.
Classe si: A classe de eventos si permite acesso a um conjunto de informaes multiplexadas em um fluxo de transporte e transmitidas periodicamente por difuso. O processo de aquisio das informaes deve obrigatoriamente ser realizado em dois passos: 1) uma requisio realizada por uma chamada event.post(), que no bloqueia a execuo do script; 2) um evento, posteriormente repassado aos tratadores de eventos registrados do script NCLua, cujo campo data contm um conjunto de subcampos que depende do tipo da informao requisitada, e que representado por uma tabela lua.
NOTA Na classe si, o filtro dependente da classe s pode ser type.
Quatro tipos de eventos so definidos pelos seguintes tipos de tabelas: type = services A tabela do tipo services consiste em um conjunto de vetores. Cada vetor possui informaes relativas a um servio multiplexado do fluxo de transporte sintonizado. Cada requisio para uma tabela do tipo de evento services deve obrigatoriamente ser realizada atravs da seguinte chamada: event.post('out', { class='si', type='services'[, index=N][, fields={field_1, field_2,, field_j}]}), onde: a) o campo index, se especificado, indica o ndice do servio; caso no seja especificado, todos os servios devem obrigatoriamente ser retornados; b) o campo fields pode ter como valor qualquer subconjunto dos subcampos definidos para a tabela retornada no campo data do evento de resposta (assim, field_i representa um dos subcampos da tabela data). Caso o campo fields no seja especificado, todos os subcampos da tabela retornada no campo data devem obrigatoriamente ser preenchidos. O evento de resposta gerado aps todas as informaes requisitadas serem processadas pelo middleware (informaes no transmitidas por difuso dentro de um intervalo mximo de tempo especificado na ABNT NBR 15603-2:2007, Tabela 6, do padro so retornadas como nulas). A tabela do campo data retornada no evento, como segue: evt = { class = 'si', type = 'services', data = { [i] = { -- cada servio est em uma posio
132
id isAvailable isPartialReception parentalControlRating runningStatus serviceType providerName serviceName stream = { [j] = { pid = <number>,
componentTag = <number>, type = <number>, regionSpecType = <number>, regionSpec } } } } Para a obteno das respostas a postagem de eventos do tipo services, recomendado que os subcampos da tabela data sejam calculados com base em tabelas SI e descritores associados ao servio [i]. recomendado que os valores dos subcampos id e runningStatus da tabela data sejam computados conforme os valores dos campos service_id e running_status, respectivamente, da tabela SDT (ver ABNT NBR 15603-2:2007, Tabela 13, que descreve o servio [i]. recomendado que a mesma relao seja estabelecida entre os subcampos providerName e serviceName da tabela data e os campos service_name e service_provider_name, respectivamente, do descritor service_descriptor (conforme a ABNT NBR 15603-2:2007). recomendado que o subcampo parentalControlRating da tabela data seja calculado com o valor do campo rating do descritor parentalControlRating, no qual o campo country_code apresente o mesmo pas referente ao valor da varivel de ambiente (n Settings) user.location. recomendado que o subcampo isAvailable da tabela data seja calculado com base no valor do campo country_code (com o grupo de pases disponveis) do descritor country_availability_descriptor (ver ABNT NBR 15603-2:2007, Subseo 8.3.6) relativo ao servio [i]. O valor true atribudo apenas se o campo country_code contiver o mesmo pas referente ao valor da varivel de ambiente (n Settings) user.location. recomendado que o subcampo isPartualReception da tabela data seja calculado com base no valor do campo service_id do descritor partial_reception_descriptor (ver ABNT NBR 15603-2:2007, Subseo 8.3.32). recomendado que a semntica ABNT NBR 15603-2:2007, Tabela H.2. recomendado que a semntica ABNT NBR 15603-2:2007, Tabela 14. do do subcampo subcampo serviceType runningStatus da tabela data seja de definida pela a = <string>,
seja
definida
acordo
com
133
recomendado que o subcampo pid da tabela stream possua o valor do campo pid do cabealho do pacote do fluxo elementar [i] (conforme ISO/IEC 13818-1). recomendado que o valor do subcampo componentTag da tabela stream seja obtido atravs do campo component_tag do descritor stream_identifier_descriptor (ver ABNT NBR 15603-2:2007, Subseo 8.3.16) relacionado ao fluxo elementar [i]. recomendado que o subcampo type da tabela stream possua a semntica definida na ISO/IEC 13818-1: 2008, Tabela 2-34, relacionada ao fluxo elementar [i]. recomendado que o subcampo regionSpecType da tabela stream defina o mtodo de codificao do campo regionSpec da mesma tabela, conforme semntica definida na ABNT NBR 15603-2:2007, Tabela 53. recomendado que o campo regionSpec da tabela stream defina a regio para a qual o fluxo elementar [i] designado. tambm recomendado que os campos regionSpec e regionSpecType sejam obtidos atravs do descritor target_region_descriptor especificado na ABNT NBR 15603-2:2007. type = mosaic A tabela do tipo mosaic consiste em um subconjunto de informaes para o mosaico que fornecido como uma matriz. A tabela , no entanto, opcional. Quando a tabela do tipo mosaic fornecida, a requisio da tabela deve obrigatoriamente ser realizada atravs da seguinte chamada: event.post('out', { class='si', type='mosaic'[, fields={field_1, field_2,, field_j}]}), onde o campo fields do evento de requisio pode ter como valor qualquer subconjunto dos subcampos definidos para a tabela retornada no campo data do evento de resposta (assim, field_i representa um dos subcampos da tabela data, como especificado a seguir). Caso o campo fields no seja especificado, todos os subcampos da tabela retornada no campo data devem obrigatoriamente ser preenchidos. O evento de resposta gerado aps todas as informaes requisitadas serem processadas pelo middleware (informaes no transmitidas por difuso dentro de um intervalo mximo de tempo especificado na ABNT NBR 15603-2:2007, Tabela 6, do padro so retornadas como nulas). A tabela do campo data retornada no evento, como segue: evt = { class = 'si', type = 'mosaic', data = { [i] = { [j] = { logicalId id linkageInfo bouquetId networkId tsId serviceId = <number>, = <number>, = <number>, = <number>, = <number>, = <number>, = <number>, presentationInfo = <number>,
134
eventId } } } }
= <number>,
NOTA Para a obteno das respostas a postagens de eventos do tipo mosaic, recomendado que os subcampos da tabela data sejam calculados com base em tabelas SI e descritores associados ao mosaico. recomendado que os valores mximos de [i] e [j], bem como os valores dos subcampos logicalId, presentationInfo, id, linkageInfo, bouquetId, networkId, tsId, serviceId e eventId da tabela data sejam obtidos atravs dos campos number_of_horizontal_elementary_cells, number_of_vertical_elementary_cells, logical_cell_id, logical_cell_presentation_info, id, cell_linkage_info, bouquet_id, original_network_id, transport_stream_id, service_id e event_id do descritor mosaic_descriptor (especificado ABNT NBR 15603-2:2007, Subseo 8.3.9), respectivamente.
type = epg A tabela do tipo epg consiste em conjunto de vetores. Cada vetor possui informaes relativas a um evento do contedo transmitido. Uma requisio da tabela do tipo epg deve obrigatoriamente ser realizada atravs de uma das possveis chamadas a seguir: 1) event.post('out', { class='si', type='epg', stage=current[, fields={field_1, field_2,, field_j}]}) onde o campo fields do evento de requisio pode ter como valor qualquer subconjunto dos subcampos definidos para a tabela retornada no campo data do evento de resposta (assim, field_i representa um dos subcampos da tabela data, como especificado a seguir). Caso o campo fields no seja especificado, todos os subcampos da tabela retornada no campo data devem obrigatoriamente ser preenchidos. Descrio: obtm as informaes do evento corrente da programao. 2) event.post('out', {class='si', type='epg', stage='next'[, eventId=<number>][, fields={field_1, field_2,, field_j}]}) onde: a) o campo eventId, quando especificado, identifica o evento imediatamente anterior ao evento que se quer as informaes. Quando no especificado indica que as informaes desejadas so as do evento seguinte ao evento corrente da programao; b) o campo fields do evento de requisio pode ter como valor qualquer subconjunto dos subcampos definidos para a tabela retornada no campo data do evento de resposta (assim, field_i representa um dos subcampos da tabela data, como especificado a seguir). Caso o campo fields no seja especificado, todos os subcampos da tabela retornada no campo data devem obrigatoriamente ser preenchidos. Descrio: obtm as informaes do evento seguinte ao evento identificado em eventId ou, caso eventId no seja especificado, do evento seguinte ao evento corrente da programao. 3) event.post('out', {class='si', type='epg', stage=schedule, startTime=<date>, endTime=<date>[, fields={field_1, field_2,, field_j}]}) onde o campo fields do evento de requisio pode ter como valor qualquer subconjunto dos subcampos definidos para a tabela retornada no campo data do evento de resposta (assim, field_i representa um dos subcampos da tabela data, como especificado a seguir). Caso o campo fields no seja especificado, todos os subcampos da tabela retornada no campo data devem obrigatoriamente ser preenchidos. Descrio: obtm as informaes dos eventos abrangidos pela faixa de tempo passada nos campos startTime e endTime que tm como valor tabelas no formato de <date>. O evento de resposta gerado aps todas as informaes requisitadas serem processadas pelo middleware (informaes no transmitidas por difuso dentro de um intervalo mximo de tempo especificado na
135
ABNT NBR 15603-2:2007, Tabela 6, do padro so retornadas como nulas). A tabela do campo data retornada no evento, como segue: evt = { class = 'si', type = 'epg', data = { [i] { startTime endTime runningStatus name originalNetworkId shortDescription extendedDescription copyrightId copyrightInfo parentalRating = <date>, = <date>, = <number>, = <string>, = <number>, = <string>, = <string>, = <string>, = <number>, = <string>, = <string>, = <string>, = <boolean>, = <string>, ={ = <number>,
dataContentLanguageCode = <string>,
[1] = <content_nibble_1>, [2] = <content_nibble_2>, [3] = <user_nibble_1>, [4] = <user_nibble_2> } }, linkage = { tsId = <number>, networkId = <number>, serviceId = <number>, type data }, hyperlink = { type = <number>, = <number>, (table 30, norma 3 vol 2) = <string>,
136
destinationType = <number>, tsId networkId eventId moduleId serviceId contentId url }, series = { id = <number>, = <number>, = <number>, = <number>, repeatLabel programPattern episodeNumber name = <string>, }, eventGroup = { type = <number>, [j] = { id tsId = <number>, = <number>, = <number>, = <number>, = <number>, = <number>, = <number>, = <number>, = <number>, = <string>,
componentTag
lastEpisodeNumber = <number>,
networkId = <number>, serviceId = <number>, } }, componentGroup = { type = <number>, [j] = { id = <number>, totalBitRate = <number>, description = <string>, caUnit = { id = <number>, -- (table 80, norma 3 vol 2) [k] = tag (<number>) } }, component = {
137
} } } } } Para a obteno das respostas a postagens de eventos do tipo epg, recomendado que os campos da tabela data sejam calculados com base em tabelas SI e descritores associados ao evento [i]. recomendado que os valores dos campos startTime, endTime, runningStatus e originalNetworkId da tabela data sejam obtidos atravs dos campos start_time, (duration + start_time), running_status e original_network_id da tabela SI event_information_section (conforme especificado na ABNT NBR 15603-2:2007, Tabela 15), respectivamente. recomendado que os valores campos name e shortDescription sejam obtidos atravs dos campos event_name_char e text_char do descritor short_event_descriptor (conforme especificado na ABNT NBR 15603-2:2007, 8.3.15), respectivamente. recomendado que o valor da campo extendedDescription seja obtido atravs do campo text_char do descritor extended_event_descriptor (conforme especificado na ABNT NBR 15603-2:2007, 8.3.7). recomendado que os valores dos campos copyrightId e copyrightInfo sejam obtidos atravs dos campos copyright_identifier e additional_copyright_info do descritor copyright_descriptor (conforme a ISO/IEC 13818-1: 2008, Tabela 2-63), respectivamente. O campo parentalRating da tabela data possui a semntica definida na ABNT NBR 15603-2:2007, Tabela 32, e recomendado que seu valor seja calculado com base no campo country_code do descritor parental_rating_descriptor e na varivel de ambiente (Settings node) user.location. O campo parentalRatingDescription da tabela data possui a semntica definida na ABNT NBR 15603-2:2007, Tabela 33, e recomendado que seu valor seja calculado com base no campo country_code do descritor parental_rating_descriptor e na varivel de ambiente (Settings node) user.location. recomendado que os valores dos campos audioLanguageCode e audioLanguageCode2 sejam obtidos atravs dos campos ISO_639_language_code e ISO_639_language_code2 do descritor audio_component_descriptor (conforme ABNT NBR 15603-2:2007, Tabela 48), respectivamente. recomendado que os valores dos campos dataContentLanguageCode e dataContextText sejam obtidos atravs dos campos ISO_639_language_code e text_char do descritor data_content_descriptor (conforme ABNT NBR 15603-2:2007, Tabela 54), respectivamente. O campo hasInteractivity da tabela data deve obrigatoriamente possuir o valor true quando o evento [i] possuir uma aplicao interativa disponvel. recomendado que o valor do campo logoURI da tabela data possua a localizao do logotipo, transmitido por uma tabela CDT (conforme ABNT NBR 15603-2:2007, 8.3.44). recomendado que os valores dos campos da tabela contentDescription sejam obtidos atravs dos campos de mesmo nome do descritor content_descriptor (conforme ABNT NBR 15603-2:2007, 8.3.5). recomendado que os valores dos campos tsId, networkId, serviceId, type e data da tabela linkage sejam obtidos atravs dos campos transport_stream_id, original_network_id, original_service_id, description_type e user_defined do descritor linkage_descriptor (conforme ABNT NBR 15603-2:2007, 8.3.40), respectivamente. recomendado que os valores dos campos type, destinationType, tsId, networkId, eventId, componentTag, moduleId, contentId e url da tabela hyperlink sejam obtidos atravs dos campos hyper_linkage_type, link_destination_type, transport_stream_id, original_network_id, event_id, component_tag, moduleId, content_id e url_char do descritor hyperlink_descriptor (conforme ABNT NBR 15603-2:2007, 8.3.29), respectivamente.
138
recomendado que os valores dos campos id, repeatLabel, programPattern, episodeNumber, lastEpisodeNumber e name da tabela series sejam obtidos atravs dos campos series_id, repeat_label, program_pattern, episode_number, last_episode_number e series_name_char do descritor series_descriptor (conforme ABNT NBR 15603-2:2007, 8.3.33), respectivamente. recomendado que os valores dos campos type, id, tsId, networkId e serviceId da tabela eventGroup sejam obtidos atravs dos campos group_type, event_id, transport_stream_id, original_network_id e service_id do descritor event_group_descriptor (conforme ABNT NBR 15603-2:2007, 8.3.34), respectivamente. recomendado que os valores dos campos type, id, totalBitRate, description, caUnit.id, caUnit.component[k].tag, tsId, networkId e serviceId da tabela componentGroup sejam obtidos atravs dos campos component_group_type, component_group_id, total_bit_rate, text_char, CA_unit_id e component_tag do descritor component_group_descriptor (conforme ABNT NBR 15603-2:2007, 8.3.37), respectivamente. type=time A tabela do tipo time consiste em informaes sobre a data e hora corrente baseadas na UTC, mas no horrio oficial do pas em que o receptor se encontra. A requisio da tabela deve obrigatoriamente ser realizada atravs da seguinte chamada: event.post('out', { class='si', type=time}), O evento de resposta gerado aps a informao sobre data e hora corrente requisitada ser processada pelo middleware (informaes no transmitidas por difuso dentro de um intervalo mximo de tempo especificado na ABNT NBR 15603-2:2007, Tabela 6, do padro so retornadas como nulas). A tabela do campo data retornada no evento, como se segue: evt = { class = 'si', type = 'time', data = { year = <number>, month = <number>, day = <number>, hours = <number>, minutes seconds }
NOTA Para a obteno das respostas a postagens de eventos do tipo time, recomendado que os campos da tabela data sejam calculados com base na tabela TOT e no descritor local_time_offset_descriptor (conforme ABNT NBR 15603-2:2007, Subseo 7.2.9).
= <number>, = <number>
Classe user: Utilizando Classe user, aplicaes podem estender suas funcionalidades, criando seus prprios eventos. Nessa classe, nenhum campo est definido (alm, do campo class).
NOTA Na classe user, o filtro dependente da classe pode ser type, se o filtro for definido.
10.3.4 Mdulo settings Exporta a tabela settings com variveis definidas pelo autor do documento NCL e variveis de ambiente reservadas, contidas no n application/x-ginga-settings. No permitido atribuir valores aos campos representando variveis no ns settings. Um erro deve ser gerado caso uma tentativa de atribuio seja feita. Propriedades de um ns settings s podem ser modificadas por meio de elos NCL.
139
A tabela settings particiona seus grupos em vrias subtabelas, correspondendo a cada grupo do n application/x-ginga-settings. Por exemplo, em um objeto NCLua, a varivel do n settings system.CPU referida como settings.system.CPU. Exemplos de uso: lang = settings.system.language age = settings.user.age val = settings.default.selBorderColor settings.service.myVar = 10 settings.user.age = 18 --> ERRO! 10.3.5 Mdulo persistent Aplicaes NCLua podem salvar dados em uma rea restrita do middleware e recuper-los entre execues. O exibidor Lua permite a uma aplicao NCLua persistir um valor para ser posteroirmente usado por ela ou por um outro objeto procedural. Para tanto, o exibidor define uma rea reservada, inacessvel a objetos NCL no procedurais. Esta rea dividida entre os grupos service, channel e shared, com a mesma semntica dos grupos homnimos do n NCL settings. No existe nenhuma varivel predefinida ou reservada nesses grupos, e objetos procedurais podem atribuir valores a essas variveis diretamente. Recomenda-se que outras linguagens procedurais, Java em particular para os objetos NCLets (<media> elements of type application/x-ginga-NCLet), ofeream uma API dando acesso mesma rea. Neste mdulo persistent, Lua oferece uma API para exportar a tabela persistent com as variveis definidas na rea reservada. O uso da tabela persistent semelhante ao uso da tabela settings, exceto pelo fato que, neste caso, o cdigo procedural pode mudar os valores dos campos. Exemplos de uso: persistent.service.total = 10 color = persistent.shared.color
140
Tabela 58 Exemplos de mapeamentos de nome entre os pacotes Ginga-J e pacotes Lua Pacote Ginga-J
org.sbtvd.net.tuning org.sbtvd.media javax.media org.dvb org.havi org.davic
Pacote Lua
ginga.org.sbtvd.net.tuning ginga.org.sbtvd.media ginga.javax.media ginga.org.dvb ginga.org.havi ginga.org.davic
10.4.3 Tipos bsicos Os tipos de dados bsicos do Java, usados na API Ginga-J, so mapeados para os tipos de dados bsicos de Lua. Esses mapeamentos so apresentados na Tabela 59. Alm dos tipos primitivos de Java, a tabela tambm especifica o mapeamento de strings e matrizes. Tabela 59 Mapeamento de tipos de dados bsicos Tipo Java
Short Int Long Float Double Byte Char Boolean Array objects String objects number number number number number number string (with only one character) boolean table string
Tipo Lua
10.4.4 Classes Toda classe Java da API Ginga-J representada em Lua como uma tabela, definida em seu respectivo pacote. Por exemplo, a classe org.sbtvd.net.tuning.ChannelManager representada em Lua como uma entrada ChannelManager no pacote ginga.org.sbtvd.net.tuning, ou seja, essa classe acessada atravs de ginga.org.sbtvd.net.tuning.ChannelManager. Todos os membros estticos de uma classe Java so mapeados para campos da tabela Lua equivalente. Cada classe representada em Lua tambm tem uma operao newInstance, que desempenha o papel de um construtor. 10.4.5 Objetos Toda vez que o mtodo newInstance fornecido por uma classe representada em Lua chamado, ele retorna uma nova instncia (objeto) dessa classe. O objeto retornado uma tabela Lua que tem todos os membros de instncia especificados por sua classe (campos e mtodos pblicos).
141
10.4.6 Objetos de callback (observadores) Muitos mtodos definidos na API Ginga-J esperam receber um objeto observador (listener) como parmetro. Esses objetos observadores podem ser implementados em Lua como tabelas que tm todos os mtodos especificados na interface do observador. 10.4.7 Excees As excees do Java tambm so mapeadas para tabelas Lua, seguindo as mesmas regras para mapear objetos do Java para Lua. Para gerar uma exceo, recomendado que um objeto observador implementado em Lua use a funo error fornecida por Lua (ver Anexo B). Para capturar uma exceo gerada por um mtodo da API, recomendado que o script Lua use a funo pcall (ver Anexo B).
11 Ponte
11.1 Reviso
A ponte de mo-dupla entre o Ginga-NCL e o Ginga-J feita: em um sentido, atravs dos relacionamentos do NCL, definidos nos elementos <link> que se referem aos elementos <media> que representam os cdigos Xlet (tipo application/x-ginga-NCLet) suportados pelo Ginga-J; e atravs dos scripts Lua (elementos <media> do tipo application/x-ginga-NCLua) que referenciam os mtodos do Ginga-J; no caminho inverso, atravs das funes do Ginga-J que podem monitorar qualquer evento NCL e tambm podem comandar alteraes em elementos e propriedades NCL, atravs de relacionamentos definidos em elementos <link> ou atravs de comandos de edio do NCL.
142
Quando o elemento <property> mapeado para um atributo do cdigo Xlet, a ao set deve obrigatoriamente atribuir um valor ao atributo. O elemento <property> pode tambm ser associado a um assessment role de um elo NCL. Nesse caso, o formatador NCL deve obrigatoriamente consultar o valor do atributo, a fim de avaliar a expresso do elo. Se o elemento <property> for mapeado para um atributo do cdigo, o valor do atributo deve obrigatoriamente ser retornado pelo player Xlet para o formatador NCL. Se o elemento <property> for mapeado para um mtodo do cdigo, o mtodo deve obrigatoriamente ser chamado e seu valor deve obrigatoriamente ser retornado pelo player Xlet para o formatador NCL.
12.2 Mtodos de codificao e transmisso de vdeo Dados de vdeo referenciados em elementos <media>
12.2.1 Transmisso de vdeo MPEG-1 12.2.1.1 Transmisso como fluxo elementar de vdeo
Para transmitir contedo de vdeo MPEG-1 como um fluxo elementar de vdeo, os dados do vdeo devem obrigatoriamente ser transmitidos como MPEG-2 packetized elementary stream (vdeo PES), com o tipo de fluxo especificado em conformidade com a atribuio de tipos de fluxos ISO/IEC 13818-1 (valor 0x01 para vdeo ISO/IEC 11172-2). 12.2.1.2 Transmisso em sees MPEG-2
Para transmitir dados de vdeo MPEG-1 por meio de sees MPEG-2 especficas (ver atribuio de tipos de fluxos para sees MPEG-2 em ISO/IEC 13818-1), um dos mtodos de transmisso a seguir deve obrigatoriamente ser usado: a) b) c) como um arquivo de fluxo multiplexado em sistemas MPEG-1 (de acordo com a ISO/IEC 11172-1); como um arquivo de fluxo elementar de vdeo MPEG-1; como um arquivo de fluxo multiplexado no formato TS especificado em 12.4.
143
12.2.2 Transmisso de vdeo MPEG-2 12.2.2.1 Transmisso como fluxo elementar de vdeo
Para transmitir contedo de vdeo MPEG-2 como um fluxo elementar de vdeo, os dados do vdeo devem obrigatoriamente ser transmitidos como MPEG-2 packetized elementary stream (vdeo PES), com o tipo de fluxo especificado de acordo com a atribuio de tipos de fluxos de acordo com ISO/IEC 13818-1 (valor 0x02 para vdeo de acordo com ISO/IEC 13818-2). 12.2.2.2 Transmisso em sees MPEG-2
Para transmitir dados de vdeo MPEG-2 por meio de sees MPEG-2 especficas (ver atribuio de tipos de fluxos para sees MPEG-2 em ISO/IEC 13818-1), um dos mtodos de transmisso a seguir deve obrigatoriamente ser usado: a) b) como um arquivo de fluxo elementar de vdeo MPEG-2; como um arquivo de fluxo multiplexado no formato TS especificado em 12.4.
12.2.3 Transmisso de vdeo MPEG-4 e H.264|MPEG-4 AVC 12.2.3.1 Transmisso como fluxo elementar de vdeo
Para transmitir contedo de vdeo MPEG-4 como um fluxo elementar de vdeo, os dados do vdeo devem obrigatoriamente ser transmitidos como MPEG-2 packetized elementary stream (vdeo PES), com o tipo de fluxo especificado de acordo com a atribuio de tipos de fluxos de acordo com ISO/IEC 13818-1 (valor 0x10 para vdeo de acordo com H.264MPEG-4 AVC). 12.2.3.2 Transmisso em sees MPEG-2
Para transmitir dados de vdeo MPEG-4 ou H.264|MPEG-4 AVC por meio de sees MPEG-2 especficas (ver atribuio de tipos de fluxos para sees MPEG-2 em ISO/IEC 13818-1), um dos mtodos de transmisso a seguir deve obrigatoriamente ser usado: a) b) como um arquivo de fluxo elementar de vdeo MPEG-4 (ou H.264|MPEG-4 AVC); como um arquivo de fluxo multiplexado no formato TS especificado em 12.4.
12.3 Mtodos de codificao e transmisso de udio dados de udio referenciados em elementos <media>
12.3.1 Transmisso de udio MPEG-1 12.3.1.1 Transmisso como fluxo elementar de udio
Para transmitir contedo de udio MPEG-1 como um fluxo elementar de udio, os dados do udio devem obrigatoriamente ser transmitidos como MPEG-2 packetized elementary stream (udio PES), com o tipo de fluxo especificado de acordo com a atribuio de tipos de fluxos ISO/IEC 13818-1 (valor 0x03 para udio ISO/IEC 11172-3). 12.3.1.2 Transmisso em sees MPEG-2
Para transmitir dados de udio MPEG-1 por meio de sees MPEG-2 especficas (ver atribuio de tipos de fluxos para sees MPEG-2 em ISO/IEC 13818-1), um dos mtodos de transmisso a seguir deve obrigatoriamente ser usado:
144
a) b) c)
como um arquivo de fluxo multiplexado em sistemas MPEG-1 (de acordo com a ISO/IEC 11172-1); como um arquivo de fluxo elementar de udio MPEG-1; como um arquivo de fluxo multiplexado no formato TS especificado em 12.4.
12.3.2 Transmisso de udio MPEG-2 12.3.2.1 Transmisso como fluxo elementar de udio
Para transmitir contedo de udio MPEG-2 AAC como um fluxo elementar de udio, os dados do udio devem obrigatoriamente ser transmitidos como MPEG-2 packetized elementary stream (udio PES), com o tipo de fluxo especificado de acordo com a atribuio de tipos de fluxos ISO/IEC 13818-1 (valor 0x0F para udio ISO/IEC 13818-7). Para transmitir contedo de udio MPEG-2 BC como um fluxo elementar de udio, os dados do udio devem obrigatoriamente ser transmitidos como MPEG-2 packetized elementary stream (PES), com o tipo de fluxo especificado de acordo com a atribuio de tipos de fluxos ISO/IEC 13818-1 (valor 0x04 para udio ISO/IEC 13818-3). 12.3.2.2 Transmisso em sees MPEG-2
Para transmitir dados de udio MPEG-2 por meio de sees MPEG-2 especficas (ver atribuio de tipos de fluxos para sees MPEG-2 em ISO/IEC 13818-1), um dos mtodos de transmisso a seguir deve obrigatoriamente ser usado: a) b) como um arquivo de fluxo elementar de udio MPEG-2; como um arquivo de fluxo multiplexado no formato TS especificado em 12.4.
12.3.3 Transmisso de udio MPEG-4 12.3.3.1 Transmisso como fluxo elementar de udio
Para transmitir contedo de udio MPEG-4 como um fluxo elementar de udio, os dados do udio devem obrigatoriamente ser transmitidos como MPEG-2 packetized elementary stream (udio PES), com o tipo de fluxo especificado em comformidade com a atribuio de tipos de fluxos ISO/IEC 13818-1 (valor 0x11 para udio ISO/IEC 14496-3). 12.3.3.2 Transmisso em sees MPEG-2
Para transmitir dados de udio MPEG-4 por meio de sees MPEG-2 especficas (ver atribuio de tipos de fluxos para sees MPEG-2 em ISO/IEC 13818-1), um dos mtodos de transmisso a seguir deve obrigatoriamente ser usado: a) b) como um arquivo de fluxo elementar de udio MPEG-4; como um arquivo de fluxo multiplexado no formato TS especificado em 12.4.
12.3.4 Transmisso de udio AC3 12.3.4.1 Transmisso como fluxo elementar de udio
Para transmitir contedo de udio AC3 como um fluxo elementar de udio, os dados de udio devem obrigatoriamente ser transmitidos como MPEG-2 packetized elementary stream (udio PES) com o tipo de udio especificado como 0x81.
145
12.3.4.2
Para transmitir dados de udio AC3 por meio de sees MPEG-2 especficas (ver atribuio de tipos de fluxos para sees MPEG-2 em ISO/IEC 13818-1), um dos mtodos de transmisso a seguir deve obrigatoriamente ser usado: a) b) como um arquivo de fluxo elementar de udio AC3; como um arquivo de fluxo multiplexado no formato TS especificado em 12.4.
12.3.5 Transmisso de udio PCM (AIFF-C) Recomenda-se que o udio AIFF-C PCM seja transmitido como um arquivo atravs de sees MPEG-2 especficas (ver atribuio de tipos de fluxos para sees MPEG-2 na ISO/IEC 13818-1).
146
12.4.4 Restries na reproduo Para ao mesmo tempo receber um servio por difuso e reproduzir um arquivo TS recebido atravs de sees MPEG-2 especficas, dois sistemas de processamento de fluxo de transporte separados so necessrios. As restries na integrao e coordenao de um contedo/evento recebido por um servio de difuso com um arquivo TS no so descritas nesta Norma.
12.5 Esquema de codificao e transmisso de imagens estticas e grficos de bitmap referenciados por elementos <media>
12.5.1 Transmisso de MPEG-2 I-frame, MPEG-4 I-VOP e H.264|MPEG-4 AVC I-picture 12.5.1.1 Transmisso em video PES para reproduo linear
Para transmitir uma imagem esttica em quadros MPEG-2 I por meio de um componente vdeo PES, o esquema de codificao deve obrigatoriamente estar conforme s convenes definidas na ABNT NBR 15606-1. O componente PES deve obrigatoriamente ser transmitido como um fluxo cujo valor de tipo igual a 0x02. Para transmitir uma imagem esttica em MPEG-4 I-VOP por meio de um componente vdeo PES, o esquema de codificao deve obrigatoriamente estar conforme s convenes definidas na ABNT NBR 15606-1. O componente PES deve obrigatoriamente ser transmitido como um fluxo cujo valor de tipo igual a 0x10. Para transmitir uma imagem esttica em H.264|MPEG-4 AVC I-picture por meio de um componente vdeo PES, o esquema de codificao deve obrigatoriamente estar conforme s convenes definidas na ABNT NBR 15606-1. O componente PES deve obrigatoriamente ser transmitido como um fluxo cujo valor de tipo igual a 0x1B. 12.5.1.2 Transmisso em sees MPEG-2 para reproduo interativa
Para transmitir uma imagem esttica em quadros MPEG-2 I por meio de sees MPEG-2, o esquema de codificao deve obrigatoriamente estar conforme a ABNT NBR 15606-1. A imagem esttica deve obrigatoriamente ser transmitida como um arquivo na seo MPEG-2. Para transmitir uma imagem esttica em MPEG4-I-VOP por meio de sees MPEG-2, o esquema de codificao deve obrigatoriamente estar conforme a ABNT NBR 15606-1. A imagem esttica deve obrigatoriamente ser transmitida como um arquivo na seo MPEG-2. Para transmitir uma imagem esttica em H.264|MPEG-4 AVC I-picture por meio de sees MPEG-2, o esquema de codificao deve obrigatoriamente estar conforme s convenes na ABNT NBR 15606-1. A imagem esttica deve obrigatoriamente ser transmitida como um arquivo na seo MPEG-2. Nesses casos, o valor do tipo de fluxo da seo MPEG-2 deve obrigatoriamente estar de acordo com a ISO/IEC 13818-1. 12.5.2 Transmisso de imagem esttica JPEG As imagens estticas JPEG devem obrigatoriamente ser transmitidas atravs de sees MPEG-2 especficas (ver a atribuio de tipos de fluxos para sees MPEG-2 na ISO/IEC 13818-1). 12.5.3 Esquema de codificao e transmisso do bitmap PNG Para os dados de bitmap PNG que so exibidos somente sob o controle de dados CLUT especificados separadamente desta Norma, os dados da paleta, dentro dos dados PNG, podem ser abreviados. O grfico de bitmap PNG deve obrigatoriamente ser transmitido atravs de sees MPEG-2 especficas (ver a atribuio de tipos de fluxos para sees MPEG-2 na ISO/IEC 13818-1).
147
12.5.4 Esquema de codificao e transmisso da animao MNG Para os dados de de bitmap PNG no formato de animao MNG que so exibidos somente sob o controle de dados CLUT especificados separadamente desta Norma, os dados da paleta dentro dos dados PNG podem ser omitidos. O grfico de animao de bitmap MNG deve obrigatoriamente ser transmitido atravs de sees MPEG-2 especficas (ver a atribuio de tipos de fluxos para sees MPEG-2 na ISO/IEC 13818-1). 12.5.5 Esquema de codificao e transmisso de dados e animao de grficos GIF Os dados de grficos e animaes GIF devem obrigatoriamente ser transmitidos atravs de sees MPEG-2 especficas (ver a atribuio de tipos de fluxos para sees MPEG-2 na ISO/IEC 13818-1).
12.6 Codificao e transmisso de caracteres - arquivos de texto externos referenciados por elementos <media>
Um arquivo de texto codificado de acordo com a ISO 8859-1 deve obrigatoriamente ser transmitido por meio de sees MPEG-2 especficas (ver a atribuio de tipos de fluxos para sees MPEG-2 na ISO/IEC 13818-1).
12.7.2.1 Transporte de comandos de edio usando descritores de evento de fluxo e carrossel de objetos DSM-CC Nos ambientes de televiso digital usual a adoo do protocolo DSM-CC para transporte de comandos de edio em fluxos elementares MPEG-2. Comandos de edio so transportados em descritores de evento de fluxo DSM-CC, que tm uma estrutura muito parecida com a dos descritores de eventos definidos pela Figura 5, como ilustra a Figura 6.
148
Sintaxe StreamEventDescriptor ( ) { descriptorTag descriptorLenght eventid Reserved eventNPT privateDataLength commandTag sequenceNumber finalFlag privateDataPayload FCS }
Nmero de bits
8 8 16 31 33 8 8 7 1 8 a 2008 8
Figura 6 Descritor de evento de fluxo DSM-CC para comandos de edio O protocolo de carrossel de objetos DSM-CC permite a transmisso cclica de objetos de eventos e sistemas de arquivos. Os objetos de eventos so utilizados para mapear nomes de eventos de fluxo a ids de eventos de fluxo, e so utilizados para informar ao Ginga sobre eventos de fluxo DSM-CC que podem ser recebidos. Os nomes dos eventos permitem especificar tipos de eventos, oferecendo maior nvel de abstrao s aplicaes do middleware. Nesse caso, convm que o Gerenciador da Base Privada, bem como os objetos de execuo procedural NCL (exemplo, NCLua, NCLet), sejam registrados como observadores dos eventos de fluxo com os quais lidam, utilizando nomes de evento, no caso: nclEditingCommand. Alm dos objetos de eventos, o protocolo de carrossel de objetos DSM-CC tambm utilizado para transportar arquivos organizados em diretrios. O demultiplexador DSM-CC responsvel por montar o sistema de arquivo no dispositivo receptor. A fim de transmitir os arquivos de Documentos NCL ou outros arquivos de Documento XML, usados nos parmetros de comandos de edio, por meio de um carrossel de objetos, o tipo de fluxo com o valor 0x0B deve obrigatoriamente ser usado. No mesmo carrossel de objetos que carrega a especificao XML, um objeto de eventos deve obrigatoriamente ser transmitido, a fim de mapear o nome nclEditingCommand para o eventId do descritor de evento do fluxo DSM-CC, que deve obrigatoriamente carregar o comando de edio NCL (ver Seo 9). O campo privateDataPayload do descritor de evento do fluxo deve obrigatoriamente carregar um conjunto de pares de referncia {uri, id}. O parmetro uri do primeiro par deve obrigatoriamente ter o esquema "x-sbtvd" e o caminho absoluto do documento XML (o caminho no servidor de dados). O parmetro id correspondente no par deve obrigatoriamente fazer referncia ao IOR de especificao do documento XML (carouselId, moduleId, objectKey; de acordo com a ABNT NBR 15606-3 e ISO/IEC 13818-6) no carrossel de objetos. Se outros sistemas de arquivos precisarem ser transmitidos usando outros carrossis de objeto, a fim de completar o comando de edio com contedo de mdia (como usual nos comandos addDocument e addNode), outros pares {uri, id} devem obrigatoriamente estar presentes no comando. Nesse caso, o parmetro uri deve obrigatoriamente ter o esquema x-sbtvd e o caminho absoluto da raiz do sistema de arquivos (o caminho no servidor de transmisso de dados) e o repectivo parmetro ior no par deve obrigatoriamente fazer referncia ao IOR (carouselId, moduleId, objectKey; de acordo com a ABNT NBR 15606-3 e ISO/IEC 13818-6) de qualquer arquivo ou diretrio filho da raiz no carrossel de objetos (o service gateway do carrossel). A Figura 7 ilustra um exemplo de transmisso de documento NCL por meio de um carrossel de objetos. Nesse exemplo, um provedor de contedo quer transmitir um programa interativo chamado "weatherConditions.ncl" armazenado em um de seus servidores de dados (sistema local de arquivos, de acordo com a Figura 7).
149
Um carrossel de objetos deve ento ser gerado (domnio de servio = 1, de acordo com a Figura 7) carregando todo o contedo do programa interativo (arquivo .ncl e todos os arquivos de mdia) e tambm um objeto de eventos (moduleId = 2 e objectKey = 2, de acordo com a Figura 7), mapeando o nome nclEditingCommand para o valor de eventId (valor 3 de acordo com a Figura 7). Um descritor de evento de fluxo tambm deve ser transmitido com o valor de eventId apropriado, no exemplo "3", e o valor 0x05 de commandTag, que indica um comando addDocument (ver Seo 9). O parmetro uri deve conter o esquema x-sbtvd e o caminho absoluto do documento NCL (C:\nclRepository\weather de acordo com a Figura 7). Finalmente, o IOR do documento NCL no carrossel de objetos transportado no parmetro xmlDocument (carouselId = 1, moduleId = 1, objectKey = 2 de acordo com a Figura 7).
Figura 7 Exemplo de uma transmisso de documento NCL 12.7.2.2 Transporte de comandos de edio usando estruturas especficas
12.7.2.2.1 Definies das estruturas de dados Descritores de evento (definidos na Seo 9) podem ser enviados em fluxo elementar MPEG-2 TS usando eventos de fluxo DSM-CC, como discutido em 12.7.1.1, ou usando qualquer protocolo para transmisso de dados sem solicitao (pushed data). Trs tipos de estrutura de dados podem ser definidos para dar suporte transmisso de parmetros dos comandos de edio NCL: mapa, metadados e arquivos de dados. Para estruturas de mapa, o campo mappingType identifica o tipo do mapa. Se o valor de mappingType for igual a 0x01 (events), um mapa-de-eventos caracterizado. Nesse caso, depois do campo mappingType, vem uma lista de identificadores de eventos, como definido na Tabela 60. Outros valores para o campo mappingType podem ser definidos, mas no so relevantes para esta Norma.
150
Tabela 60 Lista de identificadores de eventos definidos pela estrutura de mapa Sintaxe mappingStructure ( ) { mappingType for (i=1; i<N; i++){ eventId eventNameLength eventName } } Mapas do tipo events (mapas-de-eventos) so usados para mapear nomes de eventos em eventIds dos descritores de evento (ver Figura 5). Mapas-de-eventos so usados para indicar quais eventos devem obrigatoriamente ser recebidos. Nomes de eventos permitem especificar tipos de eventos, oferecendo maior nvel de abstrao s aplicaes do middleware. Nesse caso, convm que o Gerenciador de Base Privada bem como os objetos de execuo procedural NCL (exemplo, NCLua, NCLet) sejam registrados como observadores dos eventos de fluxo com os quais lidam, utilizando nomes de evento, no caso: nclEditingCommand. Quando um comando de edio NCL precisa ser enviado, um mapa-de-eventos deve obrigatoriamente ser criado, mapeando a string nclEditingCommand em um eventId de um descritor de evento selecionado (ver Figura 5). Um ou mais descritores de evento com o eventId previamente selecionado so ento criados e enviados. Esses descritores de evento podem ter os seus tempos de referncia como zero, ou podem ter sua execuo postergada para um tempo especificado. O Gerenciador de Bases Privadas deve obrigatoriamente se registrar como ouvinte de um evento nclEditingCommand para ser notificado da chegada desse tipo de evento. Cada estrutura de arquivos de dados de fato um contedo de arquivo que compe uma aplicao NCL ou um documento XML definindo uma entidade NCL: um arquivo contendo a especificao XML ou um arquivo com contedo de mdia da aplicao ou do n a ser adicionado (vdeo, udio, texto, imagem, ncl, lua etc.). Uma estrutura de metadados um documento XML, como definido no esquema a seguir. O esquema define, para cada dado entregue sem solicitao (pushed file), uma associao entre sua localizao no sistema de transporte (identificao do sistema de transporte (atributo component_tag) e a identificao do arquivo no sistema de transporte (atributo structureId)) e seu identificador de recurso universal (atributo uri). <!-XML Schema for NCL Section Metadata File This is NCL Copyright: 2000-2005 PUC-RIO/LABORATORIO TELEMIDIA, All Rights Reserved. See http://www.telemidia.puc-rio.br Public URI: http://www.ncl.org.br/NCLSectionMetadataFile.xsd Author: TeleMidia Laboratory Revision: 19/09/2006 Schema for the NCL Section Metadata File namespace. --> <schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:NCLSectionMetadataFile="http://www.ncl.org.br/NCLSectionMetadataFile" targetNamespace="http:// www.ncl.org.br/NCL3.0/NCLSectionMetadataFile" 8 8 8 to 255 8 Nmero de bits
151
elementFormDefault="qualified" attributeFormDefault="unqualified" > <complexType name="NCLSectionMetadataType"> <sequence> <sequence> <element ref="NCLSectionMetadataFile:baseData" minOccurs="0" maxOccurs="unbounded"/> </sequence> <element ref="NCLSectionMetadataFile:pushedRoot" minOccurs="0" maxOccurs="1"/> <sequence> <element ref="NCLSectionMetadataFile:pushedData" minOccurs="0" maxOccurs="unbounded"/> </sequence> </sequence> <attribute name="name" type="string" use="optional"/> <attribute name="size" type="positiveInteger" use="optional"/> </complexType> <complexType name="baseDataType"> <sequence> <element ref="NCLSectionMetadataFile:pushedRoot" minOccurs="0" maxOccurs="1"/> <sequence> <element ref="NCLSectionMetadataFile:pushedData" minOccurs="0" maxOccurs="unbounded"/> </sequence> </sequence> <attribute name="uri" type="anyURI" use="required"/> </complexType> <complexType name="pushedRootType"> <attribute name="component_tag" type="positiveInteger" use="optional"/> <attribute name="structureId" type="string" use="required"/> <attribute name="uri" type="anyURI" use="required"/> <attribute name="size" type="positiveInteger" use="optional"/> </complexType> <complexType name="pushedDataType"> <attribute name="component_tag" type="positiveInteger" use="optional"/> <attribute name="structureId" type="string" use="required"/> <attribute name="uri" type="anyURI" use="required"/> <attribute name="size" type="positiveInteger" use="optional"/> </complexType <!-- declare global elements in this module --> <element name="metadata" type="NCLSectionMetadataFile:NCLSectionMetadataType"/> <element name="baseData" type="NCLSectionMetadataFile:baseDataType"/> <element name="pushedRoot" type="NCLSectionMetadataFile:pushedRootType"/> <element name="pushedData" type="NCLSectionMetadataFile:pushedDataType"/> </schema> Para cada arquivo de documento NCL ou outros arquivos de documento XML, usados nos comandos de edio addDocument ou addNode, pelo menos uma estrutura de metadados deve obrigatoriamente ser definida. Apenas um arquivo de aplicao NCL ou um arquivo de documento XML representando um n NCL a ser inserido pode ser definido por estrutura de metadados. Mais precisamente, pode haver apenas um elemento <pushedRoot> em
152
um documento XML representando o metadados. Contudo, uma aplicao NCL (e seus arquivos de contedo) ou um documento NCL (e seus arquivos de contedo) podem se estender por mais de uma estrutura de metadados. Mais ainda, podem existir estruturas de metadados sem qualquer aplicao NCL ou documento XML descritos em seus elementos <pushedRoot> e <pushedData>. As trs estruturas anteriormente definidas podem ser transmitidas usando sistemas de transporte diferentes, como exemplificado a segtuir. 12.7.2.2.2 Transporte em um tipo especfico de seo MPEG-2
O uso de um tipo especfico de seo MPEG-2 (identificado por um valor especfico do campo table_id de uma seo privada MPEG-2), a partir de agora chamada de Seo NCL, permite a transmisso das trs estruturas de dados anteriormente definidas: mapas, metadados e arquivos de dados. Cada Seo NCL contm os dados de apenas uma estrutura. Contudo, uma estrutura pode se estender por vrias Sees. Estruturas de dados podem ser transmitidas em qualquer ordem e quantas vezes forem necessrias. O comeo de uma estrutura de dados delimitado pelo campo payload_unit_start_indicator de um pacote TS. Depois dos quatro bytes do cabealho TS, a carga (payload) do pacote TS comea, com um campo ponteiro de um byte indicando o incio de uma Seo NCL (ver ISO/IEC 13818-1). O cabealho da Seo NCL ento definido como uma seo MPEG-2 (ver ISO/IEC 13818-1). O primeiro byte da carga (payload) da Seo NCL identifica o tipo da estrutura transportada (0x01 para metadatos; 0x02 for arquivos de dados, e 0x03 para mapade-eventos). O segundo byte carrega um identificador nico da estrutura (structureId) no fluxo elementar de transporte.
NOTA O fluxo elementar e o identificador da estrutura so aqueles que so associados pela estrutura de metadados, atravs dos atributos component_tag e structureId dos elementos <pushedRoot> e <pushedData>, a localizadores de arquivos (URL).
Depois do segundo byte vem uma estrutura de dados serializada que pode ser a mappingStructure (como ilustrado pela Tabela 60), ou a estrutura de matadados (um documento XML), ou uma estrutura de arquivos de dados (um contedo de arquivo serializado). O demultiplexador de Sees NCL responsvel por montar a estrutura da aplicao no dispositivo receptor.
NOTA importante salientar que Sees NCL podem tambm transportar as estruturas de dados definidas encapsuladas em outras estruturas de dados. Por exemplo, MPE (Multi-protocol Encapsulation) pode ser usado. Nesse caso, Sees NCL seriam Sees MPEG-2 de datagrama. Mais ainda, todas as estruturas de dados mencionadas podem ainda ser envelopadas em outro formato de dados de protocolo, como, por exemplo, pacotes FLUTE.
No mesmo fluxo elementar que carrega a especificao XML (o arquivo do documento NCL ou de outro documento XML usados nos comandos de edio NCL) recomendado que um arquivo mapa-de-eventos seja transmitido, para que seja mapeado o nome nclEditingCommand no eventId do descritor de eventos que dever obrigatoriamente transportar os comandos de edio NCL, como descrito na Seo 9. O campo privateDataPayload do descritor de eventos deve obrigatoriamente carregar o par de referncias {uri, id}. Os parmetros uri tm sempre o valor null. No caso dos comandos addDocument e addNode, o parmetro id do primeiro par deve obrigatoriamente identificar o fluxo elementar (component_tag) e a estrutura de metadados que ele transporta (structureId), que, por sua vez, contm o caminho absoluto do documento NCL ou da especificao do n NCL (o caminho no servidor de dados) e a estrutura relacionada correspondente (structureId) transportada nas Sees NCL do mesmo fluxo elementar. Se outras estruturas de metadados adicionais forem necessrias para completar os comandos de edio addDocument ou addNode command, outros pares {uri, id} devem obrigatoriamente se fazer presente no comando. Nesse caso, os parmetros uri devem tambm ter o valor null e os parmetros id correspondentes devem obrigatoriamente se referir ao component_tag e o metadado structureId correspondente. A Figura 8 ilustra um exemplo de transmisso de um documento NCL atravs de Sees NCL. Nesse exemplo, um provedor de contedo quer transmitir um programa interativo chamado weatherConditions.ncl, armazenado em um de seus servidores de dados (sistema de arquivo local na Figura 8). Um fluxo elementar MPEG-2 (component_tag= 0x09) deve ento ser gerado, carregando todo o contedo do
153
programa interativo (o arquivo ncl e todos os arquivos de contedo de mdia). Um mapa-de-eventos tambm gerado (structureType=0x03; structureId=0x0C, na Figura 8), mapeando o nome nclEditingCommand ao valor de eventId (valor 3, na Figura 8). Um descritor de evento tambm deve ser transmitido, com o valor apropriado para eventId, no exemplo o valor 3, e o valor de commandTag igual a 0x05, que indica um comando addDocument (veja Seo 9). O parmetro uri deve obrigatoriamente ter o valor nulle o parmetro id deve obrigatoriamente ter o valor (component_tag= 0x09, structureId= 0x0B), como na Figura 8.
<metadata name=weatherConditions size= 110kb> <baseData uri=file://c:/nclRepository/weather/ <pushedRoot structureId=0x0A uri=weatherConditions.ncl size=10kb/> <pushedData structureId=0x09 uri=../images/brazilianMap.png size=100kb/> </baseData> </metadata>
Descritor de Evento
descriptorTag = 0 descriptorLenght= descriptorLen () eventId= 3 Reserved eventNPT = 0 privateDataLenght=dataLen() commandTag= 0x05 Sequence number= 0 finalFlag= 1 privateDataPayload= someBase, null, 0x09, 0x0B FCS = checksum()
Arquivo Mapa-de-Eventos
eventId = 3 eventNameLength = 0x0C eventName = nclEditingCommand
154
12.7.2.2.3
Uma alternativa ao transporte de estruturas de metadados diretamente em Sees NCL tratar essas estruturas como parmetros dos comandos addDocument and addNode, transportados no campo privateDataPayload dos descritores de evento. Nesse caso, o conjunto de pares {uri, id} dos comandos addDocument e addNode substitudo por parmetros da estrutura de metadados, que definem um conjunto de pares {uri, component_tag, structureId} para cada arquivo transmitido sem solicitao (pushed file). No exemplo da Figura 8, o novo transporte seria exatamente o mesmo, com exceo do descritor de evento. Ao invs desses descritores terem o par {uri; id} igual ao valor {null; 0x09, 0x0B} como parmetro, eles teriam a estrutura de metadados serializada. Na estrutura de metadados, os atributos component-tag dos elementos <pushedRoot> e <pushedData> devem obrigatoriamente, nesse caso, ser definidos, uma vez que a estrutura no mais transportada no mesmo fluxo elementar que transporta os arquivos da aplicao NCL. 12.7.2.2.4 Transporte de estruturas de metadados em sees de metadados MPEG-2
Uma outra alternativa transportar as estruturas de metadados em sees de metadados MPEG-2, transportadas em fluxos MPEG-2 do tipo 0x16. Como sempre, cada seo de metadados MPEG-2 pode conter dados de apenas uma estrutura de metadados. Contudo, uma estrutura de metadados pode se estender por vrias sees de metadados. A Tabela 61 ilustra a sintaxe da seo de metadados para o transporte de estruturas de metadados, que devem estar de acordo com ISO/IEC 13818-1:2007. Tabela 61 Sintaxe da seo para o transporte de estruturas de metadados Sintaxe Metadata section() { table_id section_syntax_indicator private_indicator random_access_indicator decoder_config_flag metadata_section_length metadata_service_id reserved section_fragment_indication version_number current_next_indicator section_number last_section_number structureId For (i=1; i< N; i++) { serialized_metadata_structure_byte } CRC_32 } Nmero de bits 8 1 1 1 1 12 8 8 2 5 1 8 8 8 8 32 Valor 0x06 1 1 1 0 inteiro inteiro a ser padronizado De acordo com a Tabela 62 inteiro 1 inteiro inteiro inteiro
155
Tabela 62 Indicao de fragmento de seo Valor 11 10 01 00 Descrio Uma nica seo de metadados carregando uma estrutura de metadados completa Primeira seo de metadados de uma srie, com dados de uma mesma estrutura de metadados ltima seo de metadados de uma srie, com dados de uma mesma estrutura de metadados Uma seo de metadados de uma srie, com dados de uma mesma estrutura de metadados, mas que no nem a primeira nem a ltima seo
Como anteriormente, no mesmo fluxo elementar que transporta a especificao XML (o arquivo do documento NCL ou um outro arquivo XML usados nos comandos de edio NCL), recomendado que um arquivo mapa-deeventos seja transmitido a fim de mapear o nome nclEditingCommand ao eventId do descritor de evento que carregar o comando de edio NCL, como descrito na Seo 9. O campo privateDataPayload do descritor de evento deve obrigatoriamente transportar um conjunto de pares de referncia {uri, id}. Os parmetros uri devem obrigatoriamente ter o valor null. No caso dos comandos addDocument e addNode, o parmetro id do primeiro par deve obrigatoriamente identificar o fluxo elementar (component_tag) do tipo= 0x16 e a estrutura de metadados (structureId) que carrega o caminho absoluto do documento NCL ou da especificao do n NCL (o caminho no servidor de dados). Se outras estruturas de metadados forem usadas para relacionar arquivos presentes no documento NCL ou na especificao do n NCL, a fim de completar os comandos addDocument ou addNode com contedos de mdia, outros pares de referncia {uri, id} devem ser definidos no comando. Nesse caso, o parmentro uri deve obrigatoriamente ter o valor null e o parmetro id correspondente no par deve obrigatoriamente referir ao component_tag e o structureId do metadado correspondente.
156
No exemplo da Figura 8, o novo cenrio seria similar. Apenas pequenas mudanas devem ser feitas de forma que o descritor de evento refira ao fluxo elementar e sua seo que carrega a estrutura de metadados (component_tag= 0x08 e structureId= 0x0B), e que a estrutura de metadados tambm refira ao fluxo elementar onde os arquivos do documento sero transportadas. A Figura 9 ilustra a nova situao.
Sistema de Arquivo Local Estrutura de Metadados
C:\nclRepository weather weatherConditions.ncl images brazilianMap.png
<metadata name=weatherConditions size= 110kb> <baseData uri=file://c:/nclRepository/weather/ <pushedRoot component_tag=0x09 structureId=0x0A uri=weatherConditions.ncl size=10kb/> <pushedData component_tag=0x09 structureId=0x09 uri=../images/brazilianMap.png size=100kb/> </baseData> </metadata>
Descritor de Eventos
descriptorTag = 0 descriptorLenght= descriptorLen () eventId= 3 Reserved eventNPT = 0 privateDataLenght=dataLen() commandTag= 0x05 Sequence number= 0 finalFlag= 1 privateDataPayload= someBase, null, 0x08, 0x0B FCS = checksum()
Figura 9 Exemplo de transmisso de documento NCL usando Sees de Metadados MPEG-2 12.7.3 Transmisso de documentos XML externo Os documentos XML externos referenciados pelos elementos <media>, como, por exemplo, um objeto de mdia XHTML, deve obrigatoriamente ser transmitido atravs de sees MPEG-2 especficas (ver a atribuio de tipos de fluxos para sees MPEG-2 na ISO/IEC 13818-1).
13 Segurana
O modelo de segurana Ginga totalmente compatvel com o modelo de segurana SBTVD. Ele lida com as mesmas reas de segurana; ou seja, autenticao de aplicativos de difuso, polticas de segurana para aplicativos, segurana sobre o canal de interao e gerenciamento de certificados. A autenticao de aplicativos Ginga-NCL deve obrigatoriamente ser realizada do mesmo modo para aplicativos Ginga-J. Se estiver assinado, o aplicativo deve obrigatoriamente seguir a estrutura de assinatura como especificado para o Ginga-J. Aplicativos Ginga-NCL no-autenticados iro operar dentro de um ambiente de caixa de areia (sand box). Os aplicativos Ginga-NCL autenticados associados a um arquivo de solicitao de permisso podem ter permisses outorgadas fora da caixa de areia.
157
Anexo A (normativo) Esquemas dos mdulos NCL 3.0 usados nos perfis TVD Bsico e TVD Avanado
158
159
160
161
162
<!-- define the labelAttrs attribute group --> <attributeGroup name="labelAttrs"> <attribute name="label" type="string" use="optional"/> </attributeGroup> <complexType name="componentAnchorPrototype"> <attribute name="id" type="ID" use="required"/> <attributeGroup ref="mediaAnchor:coordsAnchorAttrs" /> <attributeGroup ref="mediaAnchor:temporalAnchorAttrs" /> <attributeGroup ref="mediaAnchor:textAnchorAttrs" /> <attributeGroup ref="mediaAnchor:sampleAnchorAttrs" /> <attributeGroup ref="mediaAnchor:labelAttrs" /> </complexType> <!-- declare global elements in this module --> <element name="area" type="mediaAnchor:componentAnchorPrototype"/> </schema>
163
164
165
166
167
<!-- declare global attributes in this module --> <attributeGroup name="descriptorAttrs"> <attribute name="descriptor" type="string" use="optional"/> </attributeGroup> </schema>
168
169
170
171
<simpleType name="valueUnion"> <union memberTypes="string connectorAssessmentExpression:statePrototype"/> </simpleType> <complexType name="assessmentStatementPrototype" > <sequence> <element ref="connectorAssessmentExpression:attributeAssessment"/> <choice> <element ref="connectorAssessmentExpression:attributeAssessment"/> <element ref="connectorAssessmentExpression:valueAssessment"/> </choice> </sequence> <attribute name="comparator" type="connectorAssessmentExpression:comparatorPrototype" use="required"/> </complexType> <complexType name="attributeAssessmentPrototype"> <attribute name="role" type="string" use="required"/> <attribute name="eventType" type="connectorCommonPart:eventPrototype" use="required"/> <attribute name="key" type="string" use="optional"/> <attribute name="attributeType" type="connectorAssessmentExpression:attributePrototype" use="optional"/> <attribute name="offset" type="string" use="optional"/> </complexType> <complexType name="valueAssessmentPrototype"> <attribute name="value" type="connectorAssessmentExpression:valueUnion" use="required"/> </complexType> <complexType name="compoundStatementPrototype"> <choice minOccurs="1" maxOccurs="unbounded"> <element ref="connectorAssessmentExpression:assessmentStatement" /> <element ref="connectorAssessmentExpression:compoundStatement" /> </choice> <attribute name="operator" type="connectorCommonPart:logicalOperatorPrototype" use="required"/> <attribute name="isNegated" type="boolean" use="optional"/> </complexType> <!-- declare global elements in this module --> <element name="assessmentStatement" type="connectorAssessmentExpression:assessmentStatementPrototype" /> <element name="attributeAssessment" type="connectorAssessmentExpression:attributeAssessmentPrototype" /> <element name="valueAssessment" type="connectorAssessmentExpression:valueAssessmentPrototype" /> <element name="compoundStatement" type="connectorAssessmentExpression:compoundStatementPrototype" /> </schema>
172
173
<attribute name="min" type="positiveInteger" use="optional"/> <attribute name="max" type="connectorCausalExpression:maxUnion" use="optional"/> <attribute name="qualifier" type="connectorCommonPart:logicalOperatorPrototype" use="optional"/> </complexType> <complexType name="compoundConditionPrototype"> <attribute name="operator" type="connectorCommonPart:logicalOperatorPrototype" use="required"/> <attribute name="delay" type="string" use="optional"/> </complexType> <simpleType name="actionRoleUnion"> <union memberTypes="string connectorCausalExpression:actionNamePrototype"/> </simpleType> <simpleType name="actionNamePrototype"> <restriction base="string"> <enumeration value="start" /> <enumeration value="stop" /> <enumeration value="pause" /> <enumeration value="resume" /> <enumeration value="abort" /> <enumeration value="set" /> </restriction> </simpleType> <simpleType name="actionOperatorPrototype"> <restriction base="string"> <enumeration value="par" /> <enumeration value="seq" /> </restriction> </simpleType> <complexType name="simpleActionPrototype"> <attribute name="role" type="connectorCausalExpression:actionRoleUnion" use="required"/> <attribute name="eventType" type="connectorCommonPart:eventPrototype" use="optional"/> <attribute name="actionType" type="connectorCausalExpression:actionNamePrototype" use="optional"/> <attribute name="delay" type="string" use="optional"/> <attribute name="value" type="string" use="optional"/> <attribute name="repeat" type="positiveInteger" use="optional"/> <attribute name="repeatDelay" type="string" use="optional"/> <attribute name="min" type="positiveInteger" use="optional"/> <attribute name="max" type="connectorCausalExpression:maxUnion" use="optional"/> <attribute name="qualifier" type="connectorCausalExpression:actionOperatorPrototype" use="optional"/> </complexType> <complexType name="compoundActionPrototype"> <choice minOccurs="2" maxOccurs="unbounded"> <element ref="connectorCausalExpression:simpleAction" /> <element ref="connectorCausalExpression:compoundAction" /> </choice> <attribute name="operator" type="connectorCausalExpression:actionOperatorPrototype" use="required"/> <attribute name="delay" type="string" use="optional"/> </complexType>
174
<!-- declare global elements in this module --> <element name="simpleCondition" type="connectorCausalExpression:simpleConditionPrototype" /> <element name="compoundCondition" type="connectorCausalExpression:compoundConditionPrototype" /> <element name="simpleAction" type="connectorCausalExpression:simpleActionPrototype" /> <element name="compoundAction" type="connectorCausalExpression:compoundActionPrototype" /> </schema>
175
176
177
A.16 NCL30CausalConnectorFunctionality.xsd
<!-XML Schema for the NCL modules This is NCL Copyright: 2000-2005 LABORATORIO TELEMIDIA, All Rights Reserved. See http://www.telemidia.puc-rio.br Public URI: http://www.ncl.org.br/NCL3.0/modules/ NCL30CausalConnectorFunctionality.xsd Author: TeleMidia Laboratory Revision: 19/09/2006 Schema for the NCL CausalConnectorFunctionality module namespace. --> <schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:connectorCommonPart="http://www.ncl.org.br/NCL3.0/ ConnectorCommonPart" xmlns:connectorAssessmentExpression="http://www.ncl.org.br/NCL3.0/ ConnectorAssessmentExpression" xmlns:connectorCausalExpression="http://www.ncl.org.br/NCL3.0/ ConnectorCausalExpression" xmlns:causalConnector="http://www.ncl.org.br/NCL3.0/ CausalConnector" xmlns:causalConnectorFunctionality="http://www.ncl.org.br/NCL3.0/ CausalConnectorFunctionality" targetNamespace="http://www.ncl.org.br/NCL3.0/ CausalConnectorFunctionality" elementFormDefault="qualified" attributeFormDefault="unqualified"> <!-- import the definitions in the modules namespaces --> <import namespace="http://www.ncl.org.br/NCL3.0/ConnectorCommonPart" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/ NCL30ConnectorCommonPart.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/ConnectorAssessmentExpression" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/ NCL30ConnectorAssessmentExpression.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/ConnectorCausalExpression" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/ NCL30ConnectorCausalExpression.xsd"/> <import namespace="http://www.ncl.org.br/NCL3.0/CausalConnector" schemaLocation="http://www.ncl.org.br/NCL3.0/modules/ NCL30CausalConnector.xsd"/> <!-- =========================================================== --> <!-- CausalConnectorFunctionality --> <!-- =========================================================== --> <element name="connectorParam" type="connectorCommonPart:parameterPrototype"/> <!-- extends causalConnector element --> <complexType name="causalConnectorType">
178
<complexContent> <extension base="causalConnector:causalConnectorPrototype"> <sequence> <element ref="causalConnectorFunctionality:connectorParam" minOccurs="0" maxOccurs="unbounded"/> <choice> <element ref="causalConnectorFunctionality:simpleCondition" /> <element ref="causalConnectorFunctionality:compoundCondition" /> </choice> <choice> <element ref="causalConnectorFunctionality:simpleAction" /> <element ref="causalConnectorFunctionality:compoundAction" /> </choice> </sequence> </extension> </complexContent> </complexType> <!-- extends compoundCondition element --> <complexType name="compoundConditionType"> <complexContent> <extension base="connectorCausalExpression:compoundConditionPrototype"> <sequence> <choice> <element ref="causalConnectorFunctionality:simpleCondition" /> <element ref="causalConnectorFunctionality:compoundCondition" /> </choice> <choice minOccurs="1" maxOccurs="unbounded"> <element ref="causalConnectorFunctionality:simpleCondition" /> <element ref="causalConnectorFunctionality:compoundCondition" /> <element ref="causalConnectorFunctionality:assessmentStatement" /> <element ref="causalConnectorFunctionality:compoundStatement" /> </choice> </sequence> </extension> </complexContent> </complexType> <element name="causalConnector" type="causalConnectorFunctionality:causalConnectorType" substitutionGroup="causalConnector:causalConnector"/> <element name="simpleCondition" substitutionGroup="connectorCausalExpression:simpleCondition"/> <element name="compoundCondition" type="causalConnectorFunctionality:compoundConditionType" substitutionGroup="connectorCausalExpression:compoundCondition"/> <element name="simpleAction" substitutionGroup="connectorCausalExpression:simpleAction"/> <element name="compoundAction" substitutionGroup="connectorCausalExpression:compoundAction"/> <element name="assessmentStatement" substitutionGroup="connectorAssessmentExpression:assessmentStatement"/> <element name="attributeAssessment" substitutionGroup="connectorAssessmentExpression:attributeAssessment"/>
179
180
181
<complexType name="ruleBasePrototype"> <attribute name="id" type="ID" use="optional"/> </complexType> <!-- declare global elements in this module --> <element name="rule" type="testRule:rulePrototype"/> <element name="compositeRule" type="testRule:compositeRulePrototype"/> <element name="ruleBase" type="testRule:ruleBasePrototype"/> </schema>
182
183
184
185
186
187
188
189
190
<attribute name="moveUp" type="positiveInteger" use="optional"/> <attribute name="moveDown" type="positiveInteger" use="optional"/> <attribute name="focusIndex" type="positiveInteger" use="optional"/> <attribute name="focusBorderColor" type="keyNavigation:colorPrototype" use="optional"/> <attribute name="focusBorderWidth" type="string" use="optional"/> <attribute name="focusBorderTransparency" type="string" use="optional"/> <attribute name="focusScr" type="string" use="optional"/> <attribute name="focusSelScr" type="string" use="optional"/> <attribute name="selBorderColor" type="keyNavigation:colorPrototype" use="optional"/> </attributeGroup> </schema>
191
192
193
194
<enumeration value="fade"/> <enumeration value="audioFade"/> <enumeration value="audioVisualFade"/> </restriction> </simpleType> <!-- define subType attribute prototype--> <simpleType name="subTypePrototype"> <restriction base="string"> <enumeration value="bottom"/> <enumeration value="bottomCenter"/> <enumeration value="bottomLeft"/> <enumeration value="bottomLeftClockwise"/> <enumeration value="bottomLeftCounterClockwise"/> <enumeration value="bottomLeftDiagonal"/> <enumeration value="bottomRight"/> <enumeration value="bottomRightClockwise"/> <enumeration value="bottomRightCounterClockwise"/> <enumeration value="bottomRightDiagonal"/> <enumeration value="centerRight"/> <enumeration value="centerTop"/> <enumeration value="circle"/> <enumeration value="clockwiseBottom"/> <enumeration value="clockwiseBottomRight"/> <enumeration value="clockwiseLeft"/> <enumeration value="clockwiseNine"/> <enumeration value="clockwiseRight"/> <enumeration value="clockwiseSix"/> <enumeration value="clockwiseThree"/> <enumeration value="clockwiseTop"/> <enumeration value="clockwiseTopLeft"/> <enumeration value="clockwiseTwelve"/> <enumeration value="cornersIn"/> <enumeration value="cornersOut"/> <enumeration value="counterClockwiseBottomLeft"/> <enumeration value="counterClockwiseTopRight"/> <enumeration value="crossfade"/> <enumeration value="diagonalBottomLeft"/> <enumeration value="diagonalBottomLeftOpposite"/> <enumeration value="diagonalTopLeft"/> <enumeration value="diagonalTopLeftOpposite"/> <enumeration value="diamond"/> <enumeration value="doubleBarnDoor"/> <enumeration value="doubleDiamond"/> <enumeration value="down"/> <enumeration value="fadeFromColor"/> <enumeration value="fadeToColor"/> <enumeration value="fanInHorizontal"/> <enumeration value="fanInVertical"/> <enumeration value="fanOutHorizontal"/> <enumeration value="fanOutVertical"/> <enumeration value="fivePoint"/> <enumeration value="fourBlade"/> <enumeration value="fourBoxHorizontal"/> <enumeration value="fourBoxVertical"/> <enumeration value="fourPoint"/> <enumeration value="fromBottom"/> <enumeration value="fromLeft"/> <enumeration value="fromRight"/> <enumeration value="fromTop"/> <enumeration value="heart"/> <enumeration value="horizontal"/> <enumeration value="horizontalLeft"/> <enumeration value="horizontalLeftSame"/> <enumeration value="horizontalRight"/>
195
<enumeration value="horizontalRightSame"/> <enumeration value="horizontalTopLeftOpposite"/> <enumeration value="horizontalTopRightOpposite"/> <enumeration value="keyhole"/> <enumeration value="left"/> <enumeration value="leftCenter"/> <enumeration value="leftToRight"/> <enumeration value="oppositeHorizontal"/> <enumeration value="oppositeVertical"/> <enumeration value="parallelDiagonal"/> <enumeration value="parallelDiagonalBottomLeft"/> <enumeration value="parallelDiagonalTopLeft"/> <enumeration value="parallelVertical"/> <enumeration value="rectangle"/> <enumeration value="right"/> <enumeration value="rightCenter"/> <enumeration value="sixPoint"/> <enumeration value="top"/> <enumeration value="topCenter"/> <enumeration value="topLeft"/> <enumeration value="topLeftClockwise"/> <enumeration value="topLeftCounterClockwise"/> <enumeration value="topLeftDiagonal"/> <enumeration value="topLeftHorizontal"/> <enumeration value="topLeftVertical"/> <enumeration value="topRight"/> <enumeration value="topRightClockwise"/> <enumeration value="topRightCounterClockwise"/> <enumeration value="topRightDiagonal"/> <enumeration value="topToBottom"/> <enumeration value="twoBladeHorizontal"/> <enumeration value="twoBladeVertical"/> <enumeration value="twoBoxBottom"/> <enumeration value="twoBoxLeft"/> <enumeration value="twoBoxRight"/> <enumeration value="twoBoxTop"/> <enumeration value="up"/> <enumeration value="vertical"/> <enumeration value="verticalBottomLeftOpposite"/> <enumeration value="verticalBottomSame"/> <enumeration value="verticalLeft"/> <enumeration value="verticalRight"/> <enumeration value="verticalTopLeftOpposite"/> <enumeration value="verticalTopSame"/> </restriction> </simpleType> <attributeGroup name="transAttrs"> <attribute name="transIn" type="string" use="optional"/> <attribute name="transOut" type="string" use="optional"/> </attributeGroup> <!-- define the transition attribute group --> <attributeGroup name="transitionAttrs"> <attribute name="type" type="transition:typePrototype" use="required"/> <attribute name="subtype" type="transition:subTypePrototype" use="optional"/> <attribute name="fadecolor" type="string" use="optional" default="black"/> <attribute name="dur" type="string" use="optional"/> <attribute name="startProgress" use="optional" default="0.0"> <simpleType> <restriction base="decimal"> <minInclusive value="0.0"/> <maxInclusive value="1.0"/> </restriction> </simpleType>
196
</attribute> <attribute name="endProgress" use="optional" default="1.0"> <simpleType> <restriction base="decimal"> <minInclusive value="0.0"/> <maxInclusive value="1.0"/> </restriction> </simpleType> </attribute> <attribute name="direction" use="optional" default="forward"> <simpleType> <restriction base="string"> <enumeration value="forward"/> <enumeration value="reverse"/> </restriction> </simpleType> </attribute> </attributeGroup> <!-- define the transition-modifier attribute group --> <attributeGroup name="transitionModifierAttrs"> <attribute name="horzRepeat" type="decimal" use="optional" default="1.0"/> <attribute name="vertRepeat" type="decimal" use="optional" default="1.0"/> <attribute name="borderWidth" type="nonNegativeInteger" use="optional" default="0"/> <attribute name="borderColor" type="string" use="optional" default="black"/> </attributeGroup> <complexType name="transitionPrototype"> <attributeGroup ref="transition:transitionAttrs"/> <attributeGroup ref="transition:transitionModifierAttrs"/> </complexType> <!-- declare global element in this module --> <element name="transition" type="transition:transitionPrototype"/> </schema>
197
198
B.1 Introduo
NOTA Este Anexo apresenta a especificao da linguagem de programao Lua, verso 5.1. Este contedo uma traduo do livro de Roberto Ierusalimschy, Luiz Henrique de Figueiredo e Waldemar Celes, Lua 5.1 Reference Manual (Lua.org, agosto de 2006. ISBN 85-903798-3-3) e impresso novamente aqui com aprovao dos autores. O livro tambm est disponvel online, em ingls, em <http://www.lua.org/manual/5.1/>.
Lua uma linguagem de programao de extenso projetada para dar suporte programao procedimental em geral e que oferece facilidades para a descrio de dados. A linguagem tambm oferece um bom suporte para programao orientada a objetos, programao funcional e programao orientada a dados. Lua foi planejada para ser utilizada por qualquer aplicao que necessite de uma linguagem de script leve e poderosa. Lua implementada como uma biblioteca, escrita em C limpo (isto , no subconjunto comum de ANSI C e C++). Por ser uma linguagem de extenso, Lua no possui a noo de um programa principal: ela somente funciona embarcada em um programa cliente anfitrio, chamado de programa hospedeiro ou simplesmente hospedeiro. Esse programa hospedeiro pode invocar funes para executar um pedao de cdigo Lua, pode escrever e ler variveis Lua e pode registrar funes C para serem chamadas pelo cdigo Lua. Atravs do uso de funes C, Lua pode ser estendida para lidar de maneira apropriada com uma ampla variedade de domnios, permitindo assim a criao de linguagens de programao personalizadas que compartilham um arcabouo sinttico. A distribuio Lua inclui um exemplo de um programa hospedeiro chamado Lua, o qual usa a biblioteca de Lua para oferecer um interpretador de linha de comando Lua completo. Lua um software livre e, como de praxe, fornecido sem garantias, conforme dito na sua licena. A implementao descrita nesta Norma, bem como artigos tcnicos sobre Lua, esto disponveis no site oficial de Lua, www.lua.org.
B.2 A Linguagem
B.2.1 Notao utilizada
As construes da linguagem sero explicadas usando a notao BNF estendida usual, na qual {a} significa 0 ou mais a's e [a] significa um a opcional. No-terminais so mostrados como non-terminal, palavras-chave so mostradas como kword e outros smbolos terminais so mostrados como `=. A sintaxe completa de Lua est descrita em B.8.
while
199
Lua uma linguagem que diferencia minsculas de maisculas: and uma palavra reservada, mas And e AND so dois nomes vlidos diferentes. Como conveno, nomes que comeam com um sublinhado seguido por letras maisculas (tais como _VERSION) so reservados para variveis globais internas usadas por Lua. As seguintes cadeias denotam outros itens lxicos:
+ == ( ; ~= ) : * <= { , / >= } . % < [ .. ^ > ] ... # =
Cadeias de caracteres literais podem ser delimitadas atravs do uso de aspas simples ou aspas duplas, e podem conter as seguintes seqncias de escape no estilo de C: '\a' (campainha), '\b' (backspace), '\f' (alimentao de formulrio), '\n' (quebra de linha), '\r' (retorno de carro), '\t' (tabulao horizontal), '\v' (tabulao vertical), '\\' (barra invertida), '\"' (citao [aspa dupla]) e '\'' (apstrofo [aspa simples]). Alm disso, uma barra invertida seguida por uma quebra de linha real resulta em uma quebra de linha na cadeia de caracteres. Um caractere em uma cadeia de caracteres tambm pode ser especificado pelo seu valor numrico usando a seqncia de escape \ddd, onde ddd uma seqncia de at trs dgitos decimais. Se um caractere numrico representado como um seqncia de escape for seguido por um dgito, a seqncia de escape deve possuir exatamente trs dgitos. Cadeias de caracteres em Lua podem conter qualquer valor de 8 bits, incluindo zeros dentro delas, os quais podem ser especificados como '\0'. Para colocar uma aspa dupla (simples), uma quebra de linha, uma barra invertida ou inserir um zero dentro de uma cadeia de caracteres literal delimitada por aspas duplas (simples) deve-se usar uma seqncia de escape. Qualquer outro caractere pode ser inserido diretamente dentro da cadeia literal (alguns caracteres de controle podem causar problemas para o sistema de arquivos, mas Lua no tem nenhum problema em relao a eles). Cadeias literais longas tambm podem ser definidas usando um formato longo delimitado por colchetes longos. Foi definida uma abertura de colchete longo de nvel n como um abre colchete seguido por n sinais de igual seguido por outro abre colchete. Dessa forma, uma abertura de colchete longo de nvel 0 escrita como [[, uma abertura de colchete longo de nvel 1 escrita como [=[ e assim por diante. Um fechamento de colchete longo definido de maneira similar; por exemplo, um fechamento de colchete longo de nvel 4 escrito como ]====]. Uma cadeia de caracteres longa comea com uma abertura de colchete longo de qualquer nvel e termina no primeiro fechamento de colchete longo do mesmo nvel. Literais expressos desta forma podem se estender por vrias linhas, no interpretam nenhuma seqncia de escape e ignoram colchetes longos de qualquer outro nvel. Estes literais podem conter qualquer coisa, exceto um fechamento de colchete longo de nvel igual ao da abertura. Por convenincia, quando uma abertura de colchete longo imediatamente seguida por uma quebra de linha, a quebra de linha no includa na cadeia de caracteres. Como exemplo, em um sistema usando ASCII (no qual 'a' codificado como 97, quebra de linha codificado como 10 e '1' codificado como 49), os cinco literais abaixo denotam a mesma cadeia:
a = 'alo\n123"' a = "alo\n123\"" a = '\97lo\10\04923"' a = [[alo 123"]] a = [==[ alo 123"]==]
Uma constante numrica pode ser escrita com uma parte decimal opcional e com um expoente decimal opcional. Lua tambm aceita constantes hexadecimais inteiras, atravs do uso do prefixo 0x. Exemplos de constantes numricas vlidas so:
3 3.0 3.1416 314.16e-2 0.31416E1 0xff 0x56
200
Um comentrio comea com um hfen duplo (--) em qualquer lugar, desde que fora de uma cadeia de caracteres. Se o texto imediatamente depois de -- no uma abertura de colchete longo, o comentrio um comentrio curto, o qual se estende at o fim da linha. Caso contrrio, ele um comentrio longo, que se estende at o fechamento do colchete longo correspondente. Comentrios longos so freqentemente usados para desabilitar cdigo temporariamente.
Lua uma linguagem dinamicamente tipada. Isto significa que variveis no possuem tipos; somente valores possuem tipos. No existe definio de tipos na linguagem. Todos os valores carregam o seu prprio tipo. Todos os valores em Lua so valores de primeira classe. Isto significa que todos os valores podem ser armazenados em variveis, passados como argumentos para outras funes e retornados como resultados. Existem oito tipos bsicos em Lua: nil, boolean, number, string, function, userdata, thread e table. Nil o tipo do valor nil, cuja propriedade principal ser diferente de qualquer outro valor; ele geralmente representa a ausncia de um valor til. Boolean o tipo dos valores false e true. Tanto nil como false tornam uma condio falsa; qualquer outro valor torna a condio verdadeira. Number representa nmeros reais (ponto flutuante de preciso dupla). fcil construir interpretadores Lua que usem outra representao interna para nmeros, tais como preciso simples de ponto flutuante ou inteiros longos; ver o arquivo luaconf.h. O tipo string representa cadeias de caracteres. Em Lua, cadeias de caracteres podem conter qualquer caractere de 8 bits, incluindo zeros ('\0') dentro dela (ver B.2.2). Lua pode chamar (e manipular) funes escritas em Lua e funes escritas em C (ver B.2.6.9). O tipo userdata permite que dados C arbitrrios possam ser armazenados em variveis Lua. Este tipo corresponde a um bloco de memria e no tem operaes pr-definidas em Lua, exceto atribuio e teste de identidade. Contudo, atravs do uso de metatables, o programador pode definir operaes para valores userdata (ver B.2.9). Valores userdata no podem ser criados ou modificados em Lua, somente atravs da API C. Isto garante a integridade dos dados que pertencem ao programa hospedeiro. O tipo thread representa fluxos de execuo independentes e usado para implementar co-rotinas (ver B.2.12). No confundir o tipo thread de Lua com processos leves do sistema operacional. Lua d suporte a co-rotinas em todos os sistemas, at mesmo naqueles que no do suporte a processos leves. O tipo table implementa arrays associativos, isto , arrays que podem ser indexados no apenas por nmeros, mas por qualquer valor (exceto nil). Tabelas podem ser heterogneas; isto , elas podem conter valores de todos os tipos (exceto nil). Tabelas so o nico mecanismo de estruturao de dados em Lua; elas podem ser usadas para representar arrays comuns, tabelas de smbolos, conjuntos, registros, grafos, rvores etc. Para representar registros, Lua usa o nome do campo como um ndice. A linguagem d suporte a esta representao oferecendo a.name como um acar sinttico para a["name"]. Existem vrias maneiras convenientes de se criar tabelas em Lua (ver B.2.6.8). Da mesma forma que os ndices, o valor de um campo da tabela pode possuir qualquer tipo (exceto nil). Em particular, dado que funes so valores de primeira classe, campos de tabela podem conter funes. Portanto, tabelas podem tambm possuir metdos (ver B.2.6.10). Valores do tipo table, function, thread e userdata (completo) so objetos: variveis no contm realmente estes valores, somente referncias para eles. Atribuio, passagem de parmetro e retorno de funes sempre lidam com referncias para tais valores; estas operaes no implicam qualquer espcie de cpia. A funo type retorna uma cadeia de caracteres descrevendo o tipo de um dado valor.
201
B.2.3.2
Coero
Lua prov converso automtica entre valores do tipo string e do tipo number em tempo de execuo. Qualquer operao aritmtica aplicada a uma cadeia de caracteres tenta converter esta cadeia para um nmero, seguindo as regras de converso usuais. De forma anloga, sempre que um nmero usado onde uma cadeia de caracteres esperada, o nmero convertido para uma cadeia, em um formato razovel. Para um controle completo sobre como nmeros so convertidos para cadeias, usar a funo format da biblioteca string (ver string.format).
B.2.4 Variveis
Variveis so lugares usados para armazenar valores. Existem trs tipos de variveis em Lua: variveis globais, variveis locais e campos de tabelas. Um nome simples pode denotar uma varivel global ou uma varivei local (ou um parmetro formal de uma funo, que um caso particular de varivel local):
var ::= Nome
Nome denota identificadores, como definido em B.2.2. Assume-se que toda varivel uma varivel global, a menos que ela seja explicitamente declarada como uma varivel local (ver B.2.5.8). Variveis locais possuem escopo lxico: variveis locais podem ser livremente acessadas por funes definidas dentro do seu escopo (ver B.2.7). Antes da varivel receber a sua primeira atribuio, o seu valor nil. Colchetes so usados para indexar uma tabela:
var ::= expprefixo `[ exp `]
A semntica de acessos a variveis globais e a campos de tabelas pode ser mudada atravs do uso de metatabelas. Um acesso a uma varivel indexada t[i] equivalente a uma chamada gettable_event(t,i) (ver B.2.9 para uma descrio completa da funo gettable_event. Esta funo no definida nem pode ser chamada em Lua. Ela usada aqui somente para fins didticos). A sintaxe var.Nome apenas um acar sinttico para var["Nome"]:
var ::= expprefixo `. Nome
Todas as variveis globais so mantidas como campos em tabelas Lua comuns, chamadas de tabelas de ambiente ou simplesmente de ambientes (ver B.2.10). Cada funo tem sua prpria referncia para um ambiente, de forma que todas as variveis globais dentro de uma funo iro se referir para esta tabela de ambiente. Quando uma funo criada, ela herda o ambiente da funo que a criou. Para obter a tabela de ambiente de uma funo Lua, deve-se chamar getfenv. Para trocar a tabela de ambiente, deve-se chamar setfenv (a nica maneira de tratar o ambiente de funes C atravs da a biblioteca de depurao; ver B.5.11). Um acesso a uma varivel global x equivalente a _env.x, que por sua vez equivalente a
gettable_event(_env, "x")
onde _env o ambiente da funo corrente (ver B.2.9 para uma descrio completa da funo gettable_event. Esta funo no definida nem pode ser chamada em Lua. De modo anlogo, a varivel _env no definida em Lua. Elas foram usadas aqui somente para fins didticos).
202
B.2.5 Comandos
B.2.5.1 Conceitos bsicos
Lua oferece um conjunto quase convencional de comandos, similar ao conjunto de comandos disponveis em Pascal ou C. Este conjunto inclui atribuio, estruturas de controle, chamadas de funes e declaraes de variveis. B.2.5.2 Trechos
A unidade de execuo de Lua denominada de trecho. Um trecho simplesmente uma seqncia de comandos, os quais so executados seqencialmente. Cada comando pode opcionalmente ser seguido por um ponto-e-vrgula:
trecho ::= {comando [`;]}
No existem comandos vazios e, portanto, a construo ';;' no vlida. Lua trata um trecho como o corpo de uma funo annima com um nmero varivel de argumentos (ver B.2.6.10). Desta forma, trechos podem definir variveis locais, receber argumentos e retornar valores. Um trecho pode ser armazenado em um arquivo ou em uma cadeia de caracteres dentro do programa hospedeiro. Quando um trecho executado, ele primeiro pr-compilado em instrues para uma mquina virtual e depois o cdigo compilado executado por um interpretador para a mquina virtual. Trechos tambm podem ser pr-compilados em uma forma binria; ver o programa luac para mais detalhes. Programas na forma de cdigo-fonte e na forma de um arquivo-fonte j compilado so intercambiveis; Lua automaticamente determina qual o tipo do arquivo e age em conformidade com ele. B.2.5.3 Blocos
Um bloco uma lista de comandos; sintaticamente, um bloco a mesma coisa que um trecho:
bloco ::= trecho
Blocos explcitos so teis para controlar o escopo de declaraes de variveis. Blocos explcitos so tambm usados s vezes para adicionar um comando return ou break no meio de outro bloco (ver B.2.5.5). B.2.5.4 Atribuio
Lua permite atribuio mltipla. Em virtude disto, a sintaxe para atribuio define uma lista de variveis no lado esquerdo e uma lista de expresses no lado direito. Os elementos em ambos os lados so separados por vrgulas:
comando ::= listavar `= listaexp listavar ::= var {`, var} listaexp ::= exp {`, exp}
Expresses so discutidas em B.2.6. Antes da atribuio ser realizada, a lista de valores ajustada para o comprimento da lista de variveis. Se h mais valores do que o necessrio, os valores em excesso so descartados. Se h menos valores do que o necessrio, a lista estendida com tantos nil's quantos sejam necessrios. Se a lista de expresses terminar com uma chamada de funo, ento todos os valores retornados por esta chamada entram na lista de valores, antes do ajuste ser realizado (exceto quando a chamada delimitada por parnteses; ver B.2.6).
203
Um comando de atribuio primeiro avalia todas as suas expresses e somente depois que a atribuio realizada. Desta forma, o cdigo
i = 3 i, a[i] = i+1, 20
atribui 20 a a[3], sem afetar a[4] porque o i em a[i] avaliado (para 3) antes de receber o valor 4. De modo similar, a linha
x, y = y, x
troca os valores de x e y. A semntica de atribuies para variveis globais e campos de tabelas pode ser mudada atravs do uso de metatabelas. Uma atribuio para uma varivel indexada t[i] = val equivalente a settable_event(t,i,val) (ver B.2.9 para uma descrio completa da funo settable_event. Esta funo no definida nem pode ser chamada em Lua. Ela foi usada aqui somente para fins didticos). Uma atribuio a uma varivel global x = val equivalente atribuio _env.x = val, que por sua vez equivalente a
settable_event(_env, "x", val)
onde _env o ambiente da funo sendo executada (a varivel _env no definida em Lua. Ela foi usada aqui somente para fins didticos). B.2.5.5 Estruturas de controle
As estruturas de controle if, while e repeat possuem o significado usual e a sintaxe familiar:
comando ::= while exp do bloco end comando ::= repeat bloco until exp comando ::= if exp then bloco {elseif exp then bloco} [else bloco] end
Lua tambm possui um comando for, o qual possui duas variaes (ver B.2.5.6). A expresso da condio de uma estrutura de controle pode retornar qualquer valor. Tanto false como nil so considerados um valor falso. Todos os valores diferentes de nil e false so considerados como verdadeiros (em particular, o nmero 0 e a cadeia de caracteres vazia tambm so considerados valores verdadeiros). No lao repeatuntil, o bloco mais interno no termina na palavra-chave until, mas somente depois da condio. Desta forma, a condio pode referenciar variveis locais declaradas dentro do bloco do lao. O comando return usado para retornar valores de uma funo ou de um trecho (que nada mais do que uma funo). Funes e trechos podem retornar mais de um valor, de modo que a sintaxe para o comando return
comando ::= return [listaexp]
O comando break usado para terminar a execuo de um lao while, repeat ou for, pulando para o prximo comando depois do lao:
comando ::= break
Um break termina a execuo do lao mais interno. Os comandos return e break somente podem ser escritos como o ltimo comando de um bloco. Se realmente necessrio ter um return ou break no meio de um bloco, ento um bloco interno explcito pode ser usado, como nas expresses idiomticas do return end e do break end, pois agora tanto o return como o break so os ltimos comandos em seus respectivos blocos (internos).
204
B.2.5.6
Comando for
O comando for possui duas variaes: uma numrica e outra genrica. O lao for numrico repete um bloco de cdigo enquanto uma varivel de controle varia de acordo com uma progresso aritmtica. Ele possui a seguinte sintaxe:
comando ::= for nome `= exp `, exp [`, exp] do bloco end
O bloco repetido para nome comeando com o valor da primeira exp, at que ele passe o valor da segunda exp atravs de seguidos passos, sendo que a cada passo o valor da terceira exp somado a nome. De forma mais precisa, um comando for como
for v = e1, e2, e3 do block end
equivalente ao cdigo:
do local var, limit, step = tonumber(e1), tonumber(e2), tonumber(e3) if not (var and limit and step) then error() end while (step > 0 and var <= limit) or (step <= 0 and var >= limit) do local v = var block var = var + step end end
Observar o seguinte: todas as trs expresses de controle so avaliadas uma nica vez, antes do lao comear. Elas devem obrigatoriamente produzir nmeros; var, limit e step so variveis invisveis. Os nomes foram utilizados aqui somente para fins didticos; se a terceira expresso (o passo) est ausente, ento um passo de tamanho 1 usado; possvel usar break para sair de um lao for; a varivel de lao v local ao lao; no possvel usar o valor desta varivel aps o fim do for ou depois do for ter sido interrompido pelo uso de um break. Se for preciso o valor desta varivel, deve-se atribu-lo a outra varivel antes de interromper ou sair do lao. O comando for genrico funciona utilizando funes, chamadas de iteradoras. A cada iterao, a funo iteradora chamada para produzir um novo valor, parando quando este novo valor nil. O lao for genrico possui a seguinte sintaxe:
comando ::= for listadenomes in listaexp do bloco end listadenomes ::= Nome {`, Nome}
equivalente ao cdigo:
do local f, s, var = explist while true do local var_1, , var_n = f(s, var) var = var_1 if var == nil then break end block end end
205
Observar o seguinte: explist avaliada somente uma vez. Os seus resultados so uma funo iteradora, um estado e um valor inicial para a primeira varivel iteradora; f, s e var so variveis invisveis. Os nomes foram utilizados aqui somente para fins didticos; possvel usar break para sair de um lao for; as variveis de lao var_i so locais ao lao; no possvel usar os valores delas aps o trmino do for. Se precisa-se destes valores, deve-se atribu-los a outras variveis antes de interromper o lao ou sair do mesmo. B.2.5.7 Chamadas de funo como comandos
Para permitir possveis efeitos colaterais, funes podem ser executadas como comandos:
comando ::= chamadadefuncao
Neste caso, todos os valores retornados pela funo so descartados. Chamadas de funo so explicadas em B.2.6.9. B.2.5.8 Declaraes locais
Variveis locais podem ser declaradas em qualquer lugar dentro de um bloco. A declarao pode incluir uma atribuio inicial:
comando ::= local listadenomes [`= listaexp]
Caso ocorra uma atribuio inicial, a sua semntica a mesma de uma atribuio mltipla (ver B.2.5.4). Caso contrrio, todas as variveis so inicializadas com nil. Um trecho tambm um bloco (ver B.2.5.2) e portanto variveis locais podem ser declaradas em um trecho fora de qualquer bloco explcito. O escopo de uma varivel declarada desta forma se estende at o fim do trecho. As regras de visibilidade para variveis locais so explicadas em B.2.7.
B.2.6 Expresses
B.2.6.1 Expresses bsicas
Nmeros e cadeias literais so explicados em B.2.2; variveis so explicadas em B.2.4; definies de funes so explicadas em B.6.10; chamadas de funes so explicadas em B.2.6.9; construtores de tabelas so explicados em B.2.6.8. Expresses vararg, denotadas por trs pontos ('...'), somente podem ser usadas quando esto imediatamente dentro de uma funo que possui um nmero varivel de argumentos; elas so explicadas em B.2.6.10.
206
Operadores binrios compreendem operadores aritmticos (ver B.2.6.2), operadores relacionais (ver B.2.6.3), operadores lgicos (ver B.2.6.4) e o operador de concatenao (ver B.2.6.5). Operadores unrios compreendem o menos unrio (ver B.2.6.2), o not unrio (ver B.2.6.4) e o operador de tamanho unrio (ver B.2.6.6). Tanto chamadas de funes como expresses vararg podem resultar em mltiplos valores. Se a expresso usada como um comando (ver B.2.5.7) (o que somente possvel para chamadas de funes), ento a sua lista de retorno ajustada para zero elementos, descartando portanto todos os valores retornados. Se a expresso usada como o ltimo (ou o nico) elemento de uma lista de expresses, ento nenhum ajuste feito (a menos que a chamada seja delimitada por parnteses). Em todos os demais contextos, Lua ajusta a lista de resultados para um elemento, descartando todos os valores exceto o primeiro. Seguem alguns exemplos:
f() g(f(), x) g(x, f()) a,b,c = f(), x a,b = ... no -- exista um parmetro correspondente na lista) a,b,c = x, f() a,b,c = f() return f() return ... return x,y,f() {f()} {...} {f(), nil} --------f() ajustado para 2 resultados f() ajustado para 3 resultados retorna todos os resultados de f() retorna todos os resultados recebidos da lista vararg retorna x, y e todos os resultados de f() cria uma lista com todos os resultados de f() cria uma lista com todos os parmetros da lista vararg f() ajustado para 1 resultado ------ajusta para 0 resultados f() ajustado para 1 resultado g recebe x mais todos os resultados de f() f() ajustado para 1 resultado (c recebe nil) a recebe o primeiro parmetro da lista vararg, b recebe o segundo (tanto a como b podem receber nil caso
Uma expresso delimitada por parnteses sempre resulta em um nico valor. Dessa forma, (f(x,y,z)) sempre um nico valor, mesmo que f retorne mltiplos valores (o valor de (f(x,y,z)) o primeiro valor retornado por f, ou nil se f no retorna nenhum valor). B.2.6.2 Operadores aritmticos
Lua prov os operadores aritmticos usuais: os operadores binrios + (adio), - (subtrao), * (multiplicao), / (diviso), % (mdulo) e ^ (exponenciao); e o operador unrio - (negao). Se os operandos so nmeros ou cadeias de caracteres que podem ser convertidas para nmeros (ver B.2.3.2), ento todas as operaes possuem o seu significado usual. A exponenciao funciona para qualquer expoente. Por exemplo, x^(-0.5) calcula o inverso da raiz quadrada de x. Mdulo definido como
a % b == a - math.floor(a/b)*b
Ou seja, o resto de uma diviso arredondada em direo a menos infinito. B.2.6.3 Operadores relacionais
207
A igualdade (==) primeiro compara o tipo de seus operandos. Se os tipos so diferentes, ento o resultado false. Caso contrrio, os valores dos operandos so comparados. Nmeros e cadeias de caracteres so comparados de maneira usual. Objetos (valores do tipo table, userdata, thread e function) so comparados por referncia: dois objetos so considerados iguais somente se eles so o mesmo objeto. Toda vez que um novo objeto criado (um valor com tipo table, userdata, thread ou function) este novo objeto diferente de qualquer outro objeto que existia anteriormente. possvel mudar a maneira como Lua compara os tipos table e userdata atravs do uso do metamtodo "eq" (ver B.2.9). As regras de converso em B.2.3.2 no se aplicam a comparaes de igualdade. Portanto, "0"==0 avaliado como false e t[0] e t["0"] denotam posies diferentes em uma tabela. O operador ~= exatamente a negao da igualdade (==). Os operadores de ordem trabalham da seguinte forma. Se ambos os argumentos so nmeros, ento eles so comparados como tais. Caso contrrio, se ambos os argumentos so cadeias de caracteres, ento seus valores so comparados de acordo com a escolha de idioma atual. Caso contrrio, Lua tenta chamar o metamtodo "lt" ou o metamtodo "le" (ver B.2.9). B.2.6.4 Operadores lgicos
Os operadores lgicos em Lua so and, or e not. Assim como as estruturas de controle (ver B.2.5.5), todos os operadores lgicos consideram false e nil como falso e qualquer coisa diferente como verdadeiro. O operador de negao not sempre retorna false ou true. O operador de conjuno and retorna seu primeiro argumento se este valor false ou nil; caso contrrio, and retorna seu segundo argumento. O operador de disjuno or retorna seu primeiro argumento se o valor deste diferente de nil e de false; caso contrrio, or retorna o seu segundo argumento. Tanto and como or usam avaliao de curto-circuito; isto , o segundo operando avaliado somente quando necessrio. Seguem alguns exemplos:
10 or 20 10 or error() nil or "a" nil and 10 false and error() false and nil false or nil 10 and 20 --> --> --> --> --> --> --> --> 10 10 "a" nil false false nil 20
O operador de concatenao de cadeias de caracteres em Lua denotado por dois pontos ('..'). Se ambos os operandos so cadeias de caracteres ou nmeros, ento eles so convertidos para cadeias de caracteres de acordo com as regras mencionadas em B.2.3.2. Caso contrrio, o metamtodo "concat" chamado (ver B.2.9). B.2.6.6 O operador de tamanho
O operador de tamanho denotado pelo operador unrio #. O tamanho de uma cadeia de caracteres o seu nmero de bytes (isto , o significado usual de tamanho de uma cadeia quando cada caractere ocupa um byte). O tamanho de uma tabela t definido como qualquer ndice inteiro n tal que t[n] no nil e t[n+1] nil; alm disso, se t[1] nil, n pode ser zero. Para um array comum, com todos os valores diferentes de nil indo de 1 at um dado n, o seu tamanho exatamente aquele n, o ndice do seu ltimo valor. Se o array possui "buracos" (isto , valores nil entre dois outros valores diferentes de nil), ento #t pode ser qualquer um dos ndices que imediatamente precedem um valor nil (isto , ele pode considerar qualquer valor nil como o fim do array).
208
B.2.6.7
Precedncia
A precedncia de operadores em Lua segue a tabela abaixo, da menor prioridade para a maior:
or and < .. + * not ^
> / #
<=
>=
~=
==
% - (unary)
Como usual, pode-se usar parnteses para mudar as precedncias de uma expresso. Os operadores de concatenao ('..') e de exponenciao ('^') so associativos direita. Todos os demais operadores binrios so associativos esquerda. B.2.6.8 Construtores de tabelas
Construtores de tabelas so expresses que criam tabelas. Toda vez que um construtor avaliado, uma nova tabela criada. Construtores podem ser usados para criar tabelas vazias ou para criar uma tabela e inicializar alguns dos seus campos. A sintaxe geral de construtores
construtortabela ::= `{ [listadecampos] `} listadecampos ::= campo {separadordecampos campo} [separadordecampos] campo ::= `[ exp `] `= exp | Nome `= exp | exp separadordecampos ::= `, | `;
Cada campo da forma [exp1] = exp2 adiciona nova tabela uma entrada cuja chave exp1 e cujo valor exp2. Um campo da forma Nome = exp equivalente a ["Nome"] = exp. Finalmente, campos da forma exp so equivalentes a [i] = exp, onde i representa nmeros inteiros consecutivos, iniciando com 1. Campos nos outros formatos no afetam esta contagem. Por exemplo,
a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
equivalente a
do local t = {} t[f(1)] = g t[1] = "x" t[2] = "y" t.x = 1 t[3] = f(x) t[30] = 23 t[4] = 45 a = t end ----primeira exp segunda exp t["x"] = 1 terceira exp
-- quarta exp
Se o ltimo campo na lista possui a forma exp e a expresso uma chamada de funo ou uma expresso com um nmero varivel de argumentos, ento todos os valores retornados pela expresso entram na lista consecutivamente (ver B.2.6.9). Para evitar isto, colocar parnteses ao redor da chamada de funo (ou da expresso com nmero varivel de argumentos) (ver B.2.6.1). A lista de campos pode ter um separador a mais no fim, como uma convenincia para cdigo gerado automaticamente.
209
B.2.6.9
Chamadas de funo
Em uma chamada de funo, primeiro expprefixo e args so avaliados. Se o valor de expprefixo possui tipo function, ento esta funo chamada com os argumentos fornecidos. Caso contrrio, o metamtodo "call" de expprefixo chamado, tendo como primeiro parmetro o valor de expprefixo, seguido pelos argumentos originais da chamada (ver B.2.9). A forma
chamadadefuncao ::= expprefixo `: Nome args
pode ser usada para chamar "mtodos". Uma chamada v:nome(args) um acar sinttico para v.nome(v,args), com a diferena de que v avaliado somente uma vez. Argumentos possuem a seguinte sintaxe:
args ::= `( [listaexp] `) args ::= construtordetabela args ::= Cadeia
Todas as expresses fornecidas como argumento so avaliadas antes da chamada. Uma chamada da forma f{campos} um acar sinttico para f({campos}); ou seja, a lista de argumentos consiste somente em uma tabela nova. Uma chamada da forma f'cadeia' (ou f"cadeia" ou f[[cadeia]]) um acar sinttico para f('cadeia'); ou seja, a lista de argumentos consiste somente em uma cadeia de caracteres literal. Uma exceo em relao sintaxe de formato livre de Lua que no possvel colocar uma quebra de linha antes do '(' em uma chamada de funo. Esta restrio evita algumas ambigidades na linguagem. Se fosse escrito
a = f (g).x(a)
Lua poderia ver isto como um comando nico, a = f(g).x(a). Portanto, se forem desejados dois comandos, deve-se obrigatoriamente colocar um ponto-e-vrgula entre eles. Se realmente for desejado chamar f, deve-se remover a quebra de linha antes de (g). Uma chamada da forma return chamadadefuncao denominada de chamada final. Lua implementa chamadas finais prprias (ou recurses finais prprias): em uma chamada final, a funo chamada reusa a entrada na pilha da funo que a chamou. Portanto, no h limite no nmero de chamadas finais aninhadas que um programa pode executar. Contudo, uma chamada final apaga qualquer informao de depurao sobre a funo chamadora. Uma chamada final somente acontece com uma sintaxe particular, onde o return possui uma nica chamada de funo como argumento; esta sintaxe faz com que a chamada de funo retorne exatamente os valores de retorno da funo chamada. Dessa forma, nenhum dos exemplos a seguir so chamadas finais:
return (f(x)) return 2 * f(x) return x, f(x) f(x); return return x or f(x) -- o nmero de resultados ajustado para 1 -- resultados adicionais -- resultados descartados -- o nmero de resultados ajustado para 1
210
O comando
function f () body end
traduzido para
f = function () body end
O comando
function t.a.b.c.f () body end
traduzido para
t.a.b.c.f = function () body end
O comando
local function f () body end
traduzido para
local f; f = function () body end
e no para
local f = function () body end
Isto somente faz diferena quando o corpo da funo contm uma referncia para f. Uma definio de funo uma expresso executvel, cujo valor tem tipo function. Quando Lua pr-compila um trecho, todas os corpos das funes do trecho so pr-compilados tambm. Ento, sempre que Lua executa a definio de uma funo, a funo instanciada (ou fechada). Esta instncia da funo (ou fecho) o valor final da expresso. Instncias diferentes da mesma funo podem se referir a diferentes variveis locais externas e podem ter diferentes tabelas de ambiente. Parmetros comportam-se como variveis locais que so inicializadas com os valores dos argumentos:
listapar ::= listadenomes [`, `...] | `...
211
Quando uma funo chamada, a lista de argumentos ajustada para o tamanho da lista de parmetros, a no ser que a funo seja de aridade varivel ou vararg, o que indicado por trs pontos ('...') no final da sua lista de parmetros. Uma funo vararg no ajusta sua lista de argumentos; ao invs disso, ela coleta todos os argumentos extras e os fornece para a funo atravs de uma expresso vararg, a qual tambm representada como trs pontos. O valor desta expresso uma lista de todos os argumentos extras correntes, similar a uma funo com mltiplos valores de retorno. Se uma expresso vararg usada dentro de outra expresso ou no meio de uma lista de expresses, ento a sua lista de valores de retorno ajustada para um elemento. Se a expresso usada como o ltimo elemento de uma lista de expresses, ento nenhum ajuste feito (a menos que a chamada seja delimitada por parnteses). Como um exemplo, considere as seguintes definies:
function f(a, b) end function g(a, b, ...) end function r() return 1,2,3 end
Neste caso, tem-se o seguinte mapeamento de argumentos para parmetros e para as expresses vararg:
CHAMADA f(3) f(3, 4) f(3, 4, 5) f(r(), 10) f(r()) g(3) g(3, 4) g(3, 4, 5, 8) g(5, r()) PARMETROS a=3, a=3, a=3, a=1, a=1, a=3, a=3, a=3, a=5, b=nil b=4 b=4 b=10 b=2 b=nil, b=4, b=4, b=1, ... ... ... ... --> --> --> --> (nada) (nada) 5 8 2 3
Resultados so retornados usando o comando return (ver B.2.5.5). Se o controle alcana o fim de uma funo sem encontrar um comando return, ento a funo retorna sem nenhum resultado. A sintaxe de dois pontos usada para definir mtodos, isto , funes que possuem um parmetro extra implcito self. Desta forma, o comando
function t.a.b.c:f (params) body end
212
Em uma declarao como local x = x, o novo x sendo declarado no est no escopo ainda e portanto o segundo x se refere a uma varivel externa. Por causa das regras de escopo lxico, variveis locais podem ser livremente acessadas por funes definidas dentro do seu escopo. Uma varivel local usada por uma funo mais interna chamada de upvalue ou varivel local externa, dentro da funo mais interna. Cada execuo de um comando local define novas variveis locais. Considerar o exemplo a seguir:
a = {} local x = 20 for i=1,10 do local y = 0 a[i] = function () y=y+1; return x+y end end
O lao cria dez fechos (isto , dez instncias da funo annima). Cada um destes fechos usa uma varivel y diferente, enquanto todos eles compartilham a mesma varivel x.
B.2.9 Meta-tabelas
Todo valor em Lua pode ter uma metatabela. Esta metatabela uma tabela Lua comum que define o comportamento do valor original com relao a certas operaes especiais. possvel mudar vrios aspectos do comportamento de operaes sobre um valor especificando campos especficos na metatabela do valor. Por exemplo, quando um valor no numrico o operando de uma adio, Lua verifica se existe uma funo associada com o campo "__add" na metatabela do valor. Se a funo existe, Lua chama esta funo para realizar a adio. As chaves so chamadas em uma metatabela de eventos e os valores de metamtodos. No exemplo anterior, o evento "add" e o metamtodo a funo que realiza a adio. possvel obter a metatabela de qualquer valor usando a funo getmetatable. Pode-se mudar a metatabela de tabelas atravs da funo setmetatable. No se pode mudar a metatabela de outros tipos de Lua (a menos que a biblioteca de depurao for utilizada); deve-se obrigatoriamente usar a API C para fazer isto. Tabelas e objetos do tipo userdata completos possuem metatabelas individuais (embora mltiplas tabelas e objetos userdata possam compartilhar suas metatabelas); valores de todos os outros tipos compartilham uma nica metatabela por tipo. Sendo assim, h somente uma metatabela para todos os nmeros, uma para todas as cadeias de caracteres etc. Uma metatabela pode controlar como um objeto se comporta em operaes aritmticas, comparaes com relao ordem, concatenao, operao de tamanho e indexao. Uma metatabela tambm pode definir uma funo a ser chamada quando um objeto userdata coletado pelo coletor de lixo. Para cada uma destas operaes Lua associa uma chave especfica chamada um evento. Quando Lua realiza uma destas operaes sobre um valor, Lua verifica se este valor possui uma metatabela com o evento correspondente. Se este o caso, o valor associado quela chave (o metamtodo) controla como Lua ir realizar a operao.
213
Metatabelas controlam as operaes listadas a seguir. Cada operao identificada por seu nome correspondente. A chave para cada operao uma cadeia de caracteres comeando com o nome da operao sendo precedido por dois sublinhados, '__'; por exemplo, a chave para a operao "add" a cadeia "__add". A semntica destas operaes melhor explicada por meio de uma funo Lua que descreve como o interpretador executa a operao. O cdigo em Lua mostrado nesta seo meramente ilustrativo; o comportamento real est codificado no interpretador e mais eficiente do que esta simulao. Todas as funes usadas nestas descries (rawget, tonumber etc.) so apresentadas em B.5.2. Em particular, para recuperar o metamtodo de um dado objeto, a seguinte expresso utilizada:
metatable(obj)[event]
Isto , o acesso a um metamtodo no invoca outros metamtodos e o acesso a objetos que no possuem metatabelas no falha (ele simplesmente resulta em nil). "add": a operao +. A funo getbinhandler abaixo define como Lua escolhe um tratador para uma operao binria. Primeiro, Lua tenta o primeiro operando. Se este tipo no definir um tratador para a operao, ento Lua tenta o segundo operando.
function getbinhandler (op1, op2, event) return metatable(op1)[event] or metatable(op2)[event] end
"sub": a operao -. Comportamento similar ao da operao add. "mul": a operao *. Comportamento similar ao da operao add. "div": a operao /. Comportamento similar ao da operao add. "mod": a operao %. Comportamento similar operao add, com a operao o1 - floor(o1/o2)*o2 como operao primitiva. "pow": a operao ^ (exponenciao). Comportamento similar ao da operao add, com a funo pow (proveniente da biblioteca matemtica do C) como operao primitiva.
214
"len": a operao #.
function len_event (op) if type(op) == "string" then return strlen(op) -- tamanho de string primitivo elseif type(op) == "table" then return #op -- tamanho de tabela primitivo else local h = metatable(op).__len if h then -- chama o tratador passando o operando return h(op) else -- sem tratador disponvel: comportamento padro error("...") end end end
Ver B.2.6.6 para obter uma descrio do comprimento de uma tabela. "eq": a operao ==. A funo getcomphandler define como Lua escolhe um metamtodo para comparao de operadores. Um metamtodo s selecionado quando ambos os objetos em comparao tm o mesmo tipo e o mesmo metamtodo para a operao selecionada.
function getcomphandler (op1, op2, event) if type(op1) ~= type(op2) then return nil end local mm1 = metatable(op1)[event] local mm2 = metatable(op2)[event] if mm1 == mm2 then return mm1 else return nil end end
215
a >= b equivalente a b <= a. Na ausncia de um metamtodo le, Lua tenta o lt, assumindo que a <= b equivalente a not (b < a).
216
217
B.2.10 Ambientes
Alm de metatabelas, objetos do tipo thread, function e userdata possuem outra tabela associada com eles, chamada de seu ambiente. Assim como metatabelas, ambientes so tabelas normais e vrios objetos podem compartilhar o mesmo ambiente. Ambientes associados com objetos do tipo userdata no possuem significado para Lua. apenas uma convenincia para programadores associarem uma tabela a um objeto userdata. Ambientes associados com fluxos de execuo (threads) so chamados de ambientes globais. Eles so usados como o ambiente padro pelos seus fluxos de execuo e funes no aninhadas criadas pelo fluxo de execuo (atravs de loadfile, loadstring ou load) e podem ser diretamente acessados pelo cdigo C (ver B.3.4). Ambientes associados com funes C podem ser diretamente acessados pelo cdigo C (ver B.3.4). Eles so usados como o ambiente padro para outras funes C criadas pela funo. Ambientes associados com funes Lua so usados para resolver todos os acessos a variveis globais dentro da funo (ver B.2.4). Eles so usados como o ambiente padro para outras funes Lua criadas pela funo. possvel mudar o ambiente de uma funo Lua ou do fluxo de execuo que est sendo executado atualmente chamando setfenv. possvel obter o ambiente de uma funo Lua ou do fluxo de execuo sendo executado atualmente chamando getfenv. Para tratar o ambiente de outros objetos (userdata, funes C, outros fluxos de execuo), deve-se obrigatoriamente usar a API C.
218
B.2.11.2 Metamtodos de coleta de lixo Usando a API C, pode-se configurar os metamtodos do coletor de lixo para objetos userdata (ver B.2.9). Estes metamtodos tambm so chamados de finalizadores. Finalizadores permitem que se coordene a coleta de lixo de Lua com o gerenciamento de recursos externos (tais como o fechamento de arquivos, conexes de rede ou de bancos de dados ou a liberao de sua prpria memria). Objetos userdata com um campo __gc em suas metatabelas no so recolhidos imediatamente pelo coletor de lixo. Ao invs disso, Lua os coloca em uma lista. Depois que a coleta realizada, Lua faz o equivalente da seguinte funo para cada objeto userdata naquela lista:
function gc_event (userdata) local h = metatable(userdata).__gc if h then h(userdata) end end
Ao final do ciclo de coleta de lixo, os finalizadores para os objetos userdata so chamados na ordem reversa ao de sua criao, entre aqueles coletados naquele ciclo. Isto , o primeiro finalizador a ser chamado aquele associado com o objeto userdata que foi criado por ltimo no programa. O userdata s efetivamente liberado no prximo ciclo de coleta de lixo. B.2.11.3 Tabelas fracas Uma tabela fraca uma tabela cujos elementos so referncias fracas. Uma referncia fraca ignorada pelo coletor de lixo. Em outras palavras, se as nicas referncias para um objeto so referncias fracas, ento o coletor de lixo ir coletar este objeto. Uma tabela fraca pode ter chaves fracas, valores fracos ou ambos. Uma tabela com chaves fracas permite a coleta de suas chaves mas impede a coleta de seus valores. Uma tabela com chaves fracas e valores fracos permite a coleta tanto das chaves como dos valores. Em qualquer caso, se a chave coletada ou o valor coletado, o par inteiro removido da tabela. A fragilidade de uma tabela controlada pelo campo __mode de sua metatabela. Se o campo __mode uma cadeia de caracteres contendo o caractere 'k', as chaves da tabela so fracas. Se __mode contm 'v', os valores na tabela so fracos. Depois de usar uma tabela como uma metatabela, no se deve mudar o valor de seu campo __mode. Caso contrrio, o comportamento fraco das tabelas controladas por esta metatabela indefinido.
B.2.12 Co-rotinas
Lua oferece suporte a co-rotinas, tambm conhecidas como fluxos de execuo (threads) colaborativos. Uma co-rotina em Lua representa um fluxo de execuo independente. Ao contrrio de processos leves em sistemas que do suporte a mltiplos fluxos de execuo, uma co-rotina somente suspende sua execuo atravs de uma chamada explcita a uma funo de cesso. possvel criar uma co-rotina com uma chamada coroutine.create. O seu nico argumento uma funo que a funo principal da co-rotina. A funo create somente cria uma nova co-rotina e retorna uma referncia para ela (um objeto do tipo thread); ela no inicia a execuo da co-rotina. Quando a funo coroutine.resume chamada pela primeira vez, recebendo como seu primeiro argumento o objeto do tipo thread retornado por coroutine.create, a co-rotina inicia a sua execuo, na primeira linha de sua funo principal. Depois que a co-rotina comea a ser executada, ela continua executando at terminar ou ceder. Uma funo pode terminar sua execuo de duas maneiras: normalmente, quando sua funo principal retorna (explicitamente ou implicitamente, depois da ltima instruo); e de maneira anormal, se ocorre um erro no protegido. No primeiro caso, coroutine.resume retorna true mais quaisquer valores retornados pela funo principal da co-rotina. No caso de acontecerem erros, coroutine.resume retorna false mais uma mensagem de erro.
219
Uma co-rotina cede a execuo atravs de uma chamada funo coroutine.yield. Quando uma co-rotina cede, a coroutine.resume correspondente retorna imediatamente, mesmo se a cesso aconteceu dentro de uma chamada de funo aninhada (isto , no ocorreu dentro da funo principal, mas em uma funo chamada direta ou indiretamente pela funo principal). No caso de uma cesso, coroutine.resume tambm retorna true, mais quaisquer valores passados para coroutine.yield. Na prxima vez que for recomeada a execuo da mesma co-rotina, ela continua sua execuo do ponto onde ela cedeu, com a chamada para coroutine.yield retornando quaisquer argumentos extras passados para coroutine.resume. Como coroutine.create, a funo coroutine.wrap tambm cria uma co-rotina, mas ao invs de retornar a prpria co-rotina, ela retorna uma funo que, quando chamada, retoma a execuo da co-rotina. Quaisquer argumentos passados para esta funo vo como argumentos extras para coroutine.resume. coroutine.wrap retorna todos os valores retornados por coroutine.resume, exceto o primeiro (o cdigo booleano de erro). Diferentemente de coroutine.resume, coroutine.wrap no captura erros; qualquer erro propagado para o chamador. Como um exemplo, considerar o seguinde cdigo:
function foo (a) print("foo", a) return coroutine.yield(2*a) end co = coroutine.create(function (a,b) print("co-body", a, b) local r = foo(a+1) print("co-body", r) local r, s = coroutine.yield(a+b, a-b) print("co-body", r, s) return b, "end" end) print("main", print("main", print("main", print("main", coroutine.resume(co, coroutine.resume(co, coroutine.resume(co, coroutine.resume(co, 1, 10)) "r")) "x", "y")) "x", "y"))
220
B.3.2 Pilha
Lua usa uma pilha virtual para passar e receber valores de C. Cada elemento nesta pilha representa um valor Lua (nil, um nmero, uma cadeia de caracteres etc.). Sempre que Lua chama C, a funo chamada recebe uma nova pilha, que independente de pilhas anteriores e de pilhas de funes C que ainda estejam ativas. Esta pilha contm inicialmente quaisquer argumentos para a funo C e onde a funo C empilha os seus resultados para serem retornados ao chamador (ver lua_CFunction). Por convenincia, a maioria das operaes de consulta na API no segue uma disciplina estrita de pilha. Ao invs disso, elas podem se referir a qualquer elemento na pilha usando um ndice. Um ndice positivo representa uma posio absoluta na pilha (comeando em 1); um ndice negativo representa uma posio relativa ao topo da pilha. De maneira mais especfica, se a pilha possui n elementos, ento o ndice 1 representa o primeiro elemento (isto , o elemento que foi empilhado na pilha primeiro) e o ndice n representa o ltimo elemento; o ndice -1 tambm representa o ltimo elemento (isto , o elemento no topo) e o ndice -n representa o primeiro elemento. Diz-se que um ndice vlido se ele est entre 1 e o topo da pilha (isto , se 1 abs(ndice) topo).
B.3.4 Pseudo-ndices
A menos que seja dito o contrrio, qualquer funo que aceita ndices vlidos pode tambm ser chamada com pseudo-ndices, que representam alguns valores Lua que so acessveis para o cdigo C mas que no esto na pilha. Pseudo-ndices so usados para acessar o ambiente do fluxo de execuo, o ambiente da funo, o registro e os upvalues da funo C (ver B.3.5). O ambiente do fluxo de execuo (onde as variveis globais existem) est sempre no pseudo-ndice LUA_GLOBALSINDEX. O ambiente da funo C rodando est sempre no pseudo-ndice LUA_ENVIRONINDEX. Para acessar e mudar o valor de variveis globais, pode-se usar operaes de tabelas usuais sobre uma tabela de ambiente. Por exemplo, para acessar o valor de uma varivel global, fazer
lua_getfield(L, LUA_GLOBALSINDEX, varname);
221
B.3.5 Fechos C
Quando uma funo C criada, possvel associar alguns valores a ela, criando ento um fecho C; estes valores so chamados de upvalues e so acessveis para a funo sempre que ela chamada (ver lua_pushcclosure). Sempre que uma funo C chamada, seus upvalues so posicionados em pseudo-ndices especficos. Estes pseudo-ndices so gerados pela macro lua_upvalueindex. O primeiro valor associado com uma funo est na posio lua_upvalueindex(1), e assim por diante. Qualquer acesso a lua_upvalueindex(n), onde n maior do que o nmero de upvalues da funo atual, produz um ndice aceitvel (embora invlido).
B.3.6 Registro
Lua prov um registro, uma tabela predefinida, que pode ser usada por qualquer cdigo C para armazenar qualquer valor Lua que o cdigo C precise armazenar. Esta tabela est sempre localizada no pseudo-ndice LUA_REGISTRYINDEX. Qualquer biblioteca de C pode armazenar dados nesta tabela, mas ela deve tomar cuidado para escolher chaves diferentes daquelas usadas por outras bibliotecas, para evitar colises. Tipicamente, deve-se usar como chave uma cadeia de caracteres contendo o nome da sua biblioteca ou um objeto do tipo userdata leve com o endereo de um objeto C em seu cdigo. As chaves inteiras no registro so usadas pelo mecanismo de referncia, implementado pela biblioteca auxiliar, e portanto no devem ser usadas para outros propsitos.
222
lua_Alloc
typedef void * (*lua_Alloc) (void *ud, void *ptr, size_t osize, size_t nsize);
O tipo da funo de alocao de memria usada pelos estados Lua. A funo de alocao deve prover uma funcionalidade similar de realloc, mas no exatamente a mesma. Seus argumentos so ud, um ponteiro opaco passado para lua_newstate; ptr, um ponteiro para o bloco sendo alocado/realocado/liberado; osize, o tamanho original do bloco; e nsize, o novo tamanho do bloco. ptr NULL se e somente se osize zero. Quando nsize zero, a funo de alocao deve retornar NULL; se osize diferente de zero, o bloco de memria apontado por ptr deve ser liberado. Quando nsize no zero, a funo de alocao retorna NULL se e somente se ela no pode alocar o tamanho do bloco requisitado. Quando nsize no zero e osize zero, a funo de alocao deve comportar-se como malloc. Quando nsize e osize no so zero, a funo de alocao comporta-se como realloc. Lua assume que a funo de alocao nunca falha quando osize >= nsize. Segue uma implementao simples para a funo de alocao. Ela usada na biblioteca auxiliar por luaL_newstate.
static void *l_alloc (void *ud, void *ptr, size_t osize, size_t nsize) { (void)ud; /* not used */ (void)osize; /* not used */ if (nsize == 0) { free(ptr); /* ANSI requires that free(NULL) has no effect */ return NULL; } else /* ANSI requires that realloc(NULL, size) == malloc(size) */ return realloc(ptr, nsize); }
Este cdigo assume que free(NULL) no possui nenhum efeito e que realloc(NULL, size) equivalente a malloc(size). ANSI C garante esses dois comportamentos.
lua_atpanic
lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);
Estabelece uma nova funo de pnico e retorna a funo de pnico antiga. Se um erro ocorre fora de qualquer ambiente protegido, Lua chama uma funo de pnico e ento chama exit(EXIT_FAILURE), terminando ento a aplicao hospedeira. A sua funo de pnico pode evitar esta sada caso ela nunca retorne (por exemplo, fazendo uma desvio longo). A funo de pnico pode acessar a mensagem de erro no topo da pilha.
lua_call
void lua_call (lua_State *L, int nargs, int nresults);
Chama uma funo. Para chamar uma funo deve-se usar o seguinte protocolo: primeiro, a funo a ser chamada empilhada na pilha; em seguida, os argumentos da funo so empilhados em ordem direta; isto , o primeiro argumento empilhado primeiro. Por ltimo chama-se lua_call; nargs o nmero de argumentos que se empilhou na pilha. Todos os argumentos e o valor da funo so desempilhados da pilha quando a funo chamada. Os resultados da funo so empilhados na pilha quando a funo retorna. O nmero de resultados ajustado para nresults, a menos que nresults seja LUA_MULTRET. Neste caso, todos os resultados da funo so empilhados.
223
Lua cuida para que os valores retornados caibam dentro do espao da pilha. Os resultados da funo so empilhados na pilha em ordem direta (o primeiro resultado empilhado primeiro), de modo que depois da chamada o ltimo resultado est no topo da pilha. Qualquer erro dentro da funo chamada propagado para cima (com um longjmp). O seguinte exemplo mostra como o programa hospedeiro pode fazer o equivalente a este cdigo Lua:
a = f("how", t.x, 14)
O cdigo acima "balanceado": ao seu final, a pilha est de volta sua configurao original. Isto considerado uma boa prtica de programao.
lua_CFunction
typedef int (*lua_CFunction) (lua_State *L);
O tipo para funes C. A fim de se comunicar apropriadamente com Lua, uma funo C deve usar o seguinte protocolo, o qual define o modo como parmetros e resultados so passados: uma funo C recebe seus argumentos de Lua na sua pilha em ordem direta (o primeiro argumento empilhado primeiro). Portanto, quando a funo inicia, lua_gettop(L) retorna o nmero de argumentos recebidos pela funo. O primeiro argumento (se houver) est no ndice 1 e seu ltimo argumento est no ndice lua_gettop(L). Para retornar valores para Lua, uma funo C apenas os empilha na pilha, em ordem direta (o primeiro resultado empilhado primeiro) e retorna o nmero de resultados. Qualquer outro valor na pilha abaixo dos resultados ser devidamente descartado por Lua. Como uma funo Lua, uma funo C chamada por Lua tambm pode retornar muitos resultados. Como um exemplo, a seguinte funo recebe um nmero varivel de argumentos numricos e retorna a mdia e a soma deles:
static int foo (lua_State *L) { int n = lua_gettop(L); /* number of arguments */ lua_Number sum = 0; int i; for (i = 1; i <= n; i++) { if (!lua_isnumber(L, i)) { lua_pushstring(L,"incorrect argument to function `average'"); lua_error(L); } sum += lua_tonumber(L, i); } lua_pushnumber(L, sum/n); /* first result */ lua_pushnumber(L, sum); /* second result */ return 2; /* number of results */ }
224
lua_checkstack
int lua_checkstack (lua_State *L, int extra);
Garante que existem pelo menos posies extra disponveis na pilha. A funo retorna falso se ela no puder aumentar o tamanho da pilha para o tamanho desejado. Esta funo nunca comprime a pilha; se a pilha j for maior do que o novo tamanho, ela no ter o seu tamanho modificado.
lua_close
void lua_close (lua_State *L);
Destri todos os objetos no estado Lua fornecido (chamando os metamtodos de coleta de lixo correspondentes, se houver) e libera toda a memria dinmica usada por aquele estado. Em vrias plataformas, pode no ser necessrio chamar esta funo, porque todos os recursos so naturalmente liberados quando o programa hospedeiro morre. Por outro lado, programas que ficam rodando por muito tempo, como um daemon ou um servidor web, podem precisar liberar estados to logo eles no sejam mais necessrios, para evitar um crescimento demasiado do uso da memria.
lua_concat
void lua_concat (lua_State *L, int n);
Concatena os n valores no topo da pilha, desempilha-os e deixa o resultado no topo da pilha. Se n 1, o resultado o nico valor na pilha (isto , a funo no faz nada); se n 0, o resultado a cadeia de caracteres vazia. A concatenao realizada de acordo com a semntica usual de Lua (ver B.2.6.5).
lua_cpcall
int lua_cpcall (lua_State *L, lua_CFunction func, void *ud);
Chama a funo C func em modo protegido. func inicia somente com um nico elemento na sua pilha, o objeto userdata leve contendo ud. Em caso de erros, lua_cpcall retorna o mesmo cdigo de erro de lua_pcall, mais o objeto de erro no topo da pilha; caso contrrio, ela retorna zero e no muda a pilha. Todos os valores retornados por func so descartados.
lua_createtable
void lua_createtable (lua_State *L, int narr, int nrec);
Cria uma nova tabela vazia e a empilha no topo da pilha. A nova tabela possui espao pr-alocado para narr elementos array e nrec elementos no-array. Esta pr-alocao til quando se sabe exatamente quantos elementos a tabela ir ter. Caso contrrio pode-se usar a funo lua_newtable.
225
lua_dump
int lua_dump (lua_State *L, lua_Writer writer, void *data);
Descarrega uma funo como um trecho de cdigo binrio. Recebe um funo Lua no topo da pilha e produz um trecho de cdigo binrio que, se carregado novamente, resulta em uma funo equivalente quela que foi descarregada. Para produzir partes do trecho de cdigo, lua_dump chama a funo writer (ver lua_Writer) com o argumento data fornecido para escrev-los. O valor retornado o cdigo de erro retornado pela ltima chamada funo writer; 0 significa que no ocorreram erros. Esta funo no desempilha a funo Lua da pilha.
lua_equal
int lua_equal (lua_State *L, int index1, int index2);
Retorna 1 se os dois valores nos ndices aceitveis index1 e index2 so iguais, seguindo a semntica do operador == de Lua (ou seja, pode chamar metamtodos). Caso contrrio retorna 0. Tambm retorna 0 se qualquer um dos ndices no vlido.
lua_error
int lua_error (lua_State *L);
Gera um erro Lua. A mensagem de erro (que pode ser de fato um valor Lua de qualquer tipo) deve estar no topo da pilha. Esta funo faz um desvio longo e portanto nunca retorna. (ver luaL_error).
lua_gc
int lua_gc (lua_State *L, int what, int data);
Controla o coletor de lixo. Essa funo executa vrias tarefas, de acordo com o valor do parmetro what: LUA_GCSTOP: pra o coletor de lixo. LUA_GCRESTART: reinicia o coletor de lixo. LUA_GCCOLLECT: realiza um ciclo completo de coleta de lixo. LUA_GCCOUNT: retorna a quantidade de memria (em Kbytes) que est sendo usada correntemente por Lua. LUA_GCCOUNTB: retorna o resto da diviso da quantidade de bytes de memria usada correntemente por Lua por 1024.
226
LUA_GCSTEP: realiza um passo incremental de coleta de lixo. O "tamanho" do passo controlado por data (valores maiores significam mais passos) de maneira no especificada. Se for desejado controlar o tamanho do passo, deve-se ajustar de maneira experimental o valor de data. A funo retorna 1 se o passo finalizou um ciclo de coleta de lixo. LUA_GCSETPAUSE: estabelece data/100 como o novo valor para a pausa do coletor (ver B.2.11). A funo retorna o valor anterior da pausa. LUA_GCSETSTEPMUL: estabelece data/100 como o novo valor para o multiplicador de passo do coletor (ver B.2.11). A funo retorna o valor anterior do multiplicador de passo.
lua_getallocf
lua_Alloc lua_getallocf (lua_State *L, void **ud);
Retorna a funo de alocao de memria de um dado estado. Se ud no NULL, Lua armazena em *ud o ponteiro opaco passado para lua_newstate.
lua_getfenv
void lua_getfenv (lua_State *L, int index);
lua_getfield
void lua_getfield (lua_State *L, int index, const char *k);
Coloca na pilha o valor t[k], onde t o valor no ndice vlido fornecido. Como em Lua, esta funo pode disparar um metamtodo para o evento "index" (ver B.2.9).
lua_getglobal
void lua_getglobal (lua_State *L, const char *name);
Coloca na pilha o valor da global name. Esta funo definida como uma macro:
#define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, s)
lua_getmetatable
int lua_getmetatable (lua_State *L, int index);
Coloca na pilha a metatabela do valor no ndice aceitvel fornecido. Se o ndice no for vlido ou se o valor no possuir uma metatabela, a funo retorna 0 e no coloca nada na pilha.
227
lua_gettable
void lua_gettable (lua_State *L, int index);
Coloca na pilha o valor t[k], onde t o valor no ndice vlido fornecido e k o valor no topo da pilha. Esta funo desempilha a chave 'k' (colocando o resultado no seu lugar). Como em Lua, esta funo pode disparar um metamtodo para o evento "index" (ver B.2.9).
lua_gettop
int lua_gettop (lua_State *L);
Retorna o ndice do elemento no topo da pilha. Visto que os ndices comeam em 1, este resultado igual ao nmero de elementos na pilha (e portanto 0 significa uma pilha vazia).
lua_insert
void lua_insert (lua_State *L, int index);
Move o elemento no topo para o ndice vlido fornecido, deslocando os elementos acima deste ndice para abrir espao. Esta funo no pode ser chamada com um pseudo-ndice, porque um pseudo-ndice no uma posio real da pilha.
lua_Integer
typedef ptrdiff_t lua_Integer;
O tipo usado pela API Lua para representar valores inteiros. O tipo padro um ptrdiff_t, que usualmente o maior tipo inteiro com sinal que a mquina manipula "confortavelmente".
lua_isboolean
int lua_isboolean (lua_State *L, int index);
Retorna 1 se o valor no ndice aceitvel fornecido possuir tipo booleano e 0 caso contrrio.
lua_iscfunction
int lua_iscfunction (lua_State *L, int index);
Retorna 1 se o valor no ndice aceitvel fornecido for uma funo C e 0 caso contrrio.
228
lua_isfunction
int lua_isfunction (lua_State *L, int index);
Retorna 1 se o valor no ndice aceitvel fornecido for uma funo (C ou Lua) e 0 caso contrrio.
lua_islightuserdata
int lua_islightuserdata (lua_State *L, int index);
Retorna 1 se o valor no ndice aceitvel fornecido for um objeto userdata leve e 0 caso contrrio.
lua_isnil
int lua_isnil (lua_State *L, int index);
lua_isnone
int lua_isnone (lua_State *L, int index);
Retorna 1 se o ndice aceitvel fornecido no for vlido (isto , se ele se referir a um elemento fora do espao da pilha corrente) e 0 em caso contrrio.
lua_isnoneornil
int lua_isnoneornil (lua_State *L, int index);
Retorna 1 se o ndice aceitvel fornecido no for vlido (isto , se ele se referir a um elemento fora do espao da pilha corrente) ou se o valor neste ndice for nil e 0 caso contrrio.
lua_isnumber
int lua_isnumber (lua_State *L, int index);
Retorna 1 se o valor no ndice aceitvel fornecido for um nmero ou uma cadeia de caracteres que pode ser convertida para um nmero e 0 em caso contrrio.
lua_isstring
int lua_isstring (lua_State *L, int index);
Retorna 1 se o valor no ndice aceitvel fornecido for uma cadeia de caracteres ou um nmero (o qual sempre pode ser convertido para uma cadeia) e 0 caso contrrio.
229
lua_istable
int lua_istable (lua_State *L, int index);
Retorna 1 se o valor no ndice aceitvel fornecido for uma tabela e 0 caso contrrio.
lua_isthread
int lua_isthread (lua_State *L, int index);
Retorna 1 se o valor no ndice aceitvel fornecido for do tipo thread e 0 caso contrrio.
lua_isuserdata
int lua_isuserdata (lua_State *L, int index);
Retorna 1 se o valor no ndice aceitvel fornecido for um objeto userdata (completo ou leve) e 0 caso contrrio.
lua_lessthan
int lua_lessthan (lua_State *L, int index1, int index2);
Retorna 1 se o valor no ndice aceitvel index1 for menor do que o valor no ndice aceitvel index2, seguindo a semntica do operador < de Lua (ou seja, pode chamar metamtodos). Caso contrrio, retorna 0. Tambm retorna 0 se qualquer um dos ndices no for vlido.
lua_load
int lua_load (lua_State *L, lua_Reader reader, void *data, const char *chunkname);
Carrega um trecho de cdigo Lua. Se no ocorrer nenhum erro, lua_load empilha o trecho compilado como uma funo Lua no topo da pilha. Caso contrrio, empilha uma mensagem de erro. Os valores de retorno de lua_load so: 0 --- sem erros; LUA_ERRSYNTAX --- erro de sintaxe durante a pr-compilao. LUA_ERRMEM --- erro de alocao de memria.
Esta funo somente carrega um trecho; ela no o executa. lua_load automaticamente detecta se o trecho est na forma de texto ou na forma binria e o carrega de maneira correta (ver o programa luac). A funo lua_load usa uma funo reader fornecida pelo usurio para ler o trecho de cdigo (ver lua_Reader). O argumento data um valor opaco passado para a funo de leitura. O argumento chunkname d um nome ao trecho, o qual usado para mensagens de erro e em informaes de depurao (ver B.3.9).
230
lua_newstate
lua_State *lua_newstate (lua_Alloc f, void *ud);
Cria um estado novo independente. Retorna NULL se no puder criar o estado (devido falta de memria). O argumento f a funo de alocao; Lua faz toda a alocao de memria para este estado atravs desta funo. O segundo argumento, ud, um ponteiro opaco que Lua simplesmente passa para a funo de alocao a cada chamada.
lua_newtable
void lua_newtable (lua_State *L);
Cria uma nova tabela vazia e a coloca na pilha. equivalente a lua_createtable(L, 0, 0). lua_newthread
lua_State *lua_newthread (lua_State *L);
Cria um novo objeto do tipo thread, coloca-o na pilha e retorna um ponteiro para um lua_State que representa este novo fluxo de execuo. O novo fluxo de execuo retornado por esta funo compartilha todos os objetos globais (tais como tabelas) com o estado original, mas possui uma pilha de execuo independente. No h uma funo explcita para terminar ou destruir um fluxo de execuo. Objetos do tipo thread esto sujeitos coleta de lixo, assim como qualquer outro objeto de Lua.
lua_newuserdata
void *lua_newuserdata (lua_State *L, size_t size);
Esta funo aloca um novo bloco de memria com o tamanho fornecido, coloca na pilha um novo objeto userdata completo com o endereo do bloco e retorna este endereo. Objetos userdata representam valores C em Lua. Um userdata completo representa um bloco de memria. Ele um objeto (assim como uma tabela): deve-se cri-lo, ele pode ter sua prpria metatabela e pode-se detectar quando ele est sendo coletado. Um objeto userdata completo somente igual a ele mesmo (usando a igualdade primitiva, sem o uso de metamtodos). Quando Lua coleta um userdata completo com um metamtodo gc, Lua chama o metamtodo e marca o userdata como finalizado. Quando este userdata coletado novamente ento Lua libera sua memria correspondente.
231
lua_next
int lua_next (lua_State *L, int index);
Desempilha uma chave da pilha e empilha um par chave-valor da tabela no ndice fornecido (o "prximo" par depois da chave fornecida). Se no h mais elementos na tabela, ento lua_next retorna 0 (e no empilha nada). Um percorrimento tpico parece com este:
/* table is in the stack at index `t' lua_pushnil(L); /* first key */ while (lua_next(L, t) != 0) { /* `key' is at index -2 and `value' printf("%s - %s\n", lua_typename(L, lua_type(L, -2)), lua_pop(L, 1); /* removes `value'; } */ at index -1 */ lua_typename(L, lua_type(L, -1))); keeps `key' for next iteration */
Durante o percorrimento de uma tabela, no chamar lua_tolstring diretamente sobre uma chave, a menos que se saiba que a chave realmente uma cadeia de carecteres. Lembrar que lua_tolstring altera o valor no ndice fornecido; isto confunde a prxima chamada para lua_next.
lua_Number
typedef double lua_Number;
O tipo de nmeros em Lua. Por padro, ele double, mas pode ser mudado em luaconf.h. Atravs do arquivo de configurao possvel mudar Lua para operar com outro tipo para nmeros (por exemplo, float ou long).
lua_objlen
size_t lua_objlen (lua_State *L, int index);
Retorna o "tamanho" do valor no ndice aceitvel fornecido: para cadeias de caracteres o tamanho da cadeia; para tabelas o resultado do operador de tamanho ('#'); para objetos do tipo userdata o tamanho do bloco de memria alocado para o userdata; para outros valores, o tamanho 0.
lua_pcall
lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);
Chama uma funo em modo protegido. Tanto nargs quanto nresults possuem o mesmo significado que possuam em lua_call. Se no h erros durante a chamada, lua_pcall comporta-se exatamente como lua_call. Contudo, se h qualquer erro, lua_pcall o captura, coloca um nico valor na pilha (a mensagem de erro) e retorna um cdigo de erro. Como lua_call, lua_pcall sempre remove a funo e seus argumentos da pilha.
232
Se errfunc 0, ento a mensagem de erro retornada na pilha exatamente a mensagem de erro original. Caso contrrio, errfunc o ndice na pilha de um funo de tratamento de erros. (Na implementao atual, este ndice no pode ser um pseudo-ndice.) No caso de erros de tempo de execuo, esta funo ser chamada com a mensagem de erro e seu valor de retorno ser a mensagem retornada na pilha por lua_pcall. Tipicamente, a funo de tratamento de erros usada para adicionar mais informao de depurao mensagem de erro, como um trao da pilha. Tal informao no pode ser obtida aps o retorno de lua_pcall, pois neste ponto a pilha j foi desfeita. A funo lua_pcall retorna 0 em caso de sucesso ou um dos seguintes cdigos de erro (definidos em lua.h): LUA_ERRRUN: um erro em tempo de execuo. LUA_ERRMEM: erro de alocao de memria. Para tais erros, Lua no chama a funo de tratamento erros. LUA_ERRERR: erro durante a execuo da funo de tratamento de erros.
lua_pop
void lua_pop (lua_State *L, int n);
lua_pushboolean
void lua_pushboolean (lua_State *L, int b);
lua_pushcclosure
void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);
Empilha um novo fecho C na pilha. Quando uma funo C criada, possvel associar alguns valores a ela, criando ento um fecho C (ver B.3.5); estes valores so ento acessveis para a funo sempre que ela chamada. Para associar valores com uma funo C, primeiro estes valores devem ser colocados na pilha (quando h mltiplos valores, o primeiro valor empilhado primeiro). Ento lua_pushcclosure chamada para criar e colocar a funo C na pilha, com o argumento n informando quantos valores devem ser associados com a funo. lua_pushcclosure tambm desempilha estes valores da pilha.
233
lua_pushcfunction
void lua_pushcfunction (lua_State *L, lua_CFunction f);
Empilha uma funo C na pilha. Esta funo recebe um ponteiro para uma funo C e coloca na pilha um valor Lua do tipo function que, quando chamado, invoca a funo C correspondente. Qualquer funo para ser registrada em Lua deve seguir o protocolo correto para receber seus parmetros e retornar seus resultados (ver lua_CFunction). lua_pushcfunction definida como uma macro:
#define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0)
lua_pushfstring
const char *lua_pushfstring (lua_State *L, const char *fmt, ...);
Coloca na pilha uma cadeia de caracteres formatada e retorna um ponteiro para esta cadeia. Ela similar funo C sprintf, mas possui algumas diferenas importantes: no preciso alocar espao para o resultado: o resultado uma cadeia de caracteres e Lua cuida da alocao de memria (e da desalocao, atravs da coleta de lixo); os especificadores de converso so bastante restritos. No h flags, tamanhos ou precises. Os especificadores de converso podem ser somente '%%' (insere um '%' na cadeia), '%s' (insere uma cadeia terminada por zero, sem restries de tamanho), '%f' (insere um lua_Number), '%p' (insere um ponteiro como um nmero hexadecimal), '%d' (insere um int) e '%c' (insere um int como um caractere).
lua_pushinteger
void lua_pushinteger (lua_State *L, lua_Integer n);
lua_pushlightuserdata
void lua_pushlightuserdata (lua_State *L, void *p);
Coloca um objeto do tipo userdata leve na pilha. Um userdata representa valores de C em Lua. Um userdata leve representa um ponteiro. Ele um valor (como um nmero): no se pode cri-lo, ele no possui uma metatabela individual e ele no coletado (uma vez que ele nunca foi criado). Um userdata leve igual a "qualquer" userdata leve com o mesmo endereo C.
234
lua_pushlstring
void lua_pushlstring (lua_State *L, const char *s, size_t len);
Empilha a cadeia de caracteres apontada por s com tamanho len na pilha. Lua cria (ou reusa) uma cpia interna da cadeia fornecida, de forma que a memria apontada por s pode ser liberada ou reutilizada imediatamente aps o retorno da funo. A cadeia pode conter zeros dentro dela.
lua_pushnil
void lua_pushnil (lua_State *L);
lua_pushnumber
void lua_pushnumber (lua_State *L, lua_Number n);
lua_pushstring
void lua_pushstring (lua_State *L, const char *s);
Empilha a cadeia terminada por zero apontada por s na pilha. Lua cria (ou reusa) uma cpia interna da cadeia fornecida, de forma que a memria apontada por s pode ser liberada ou reutilizada imediatamente aps o retorno da funo. A cadeia no pode conter zeros dentro dela; assume-se que a cadeia termina no primeiro zero.
lua_pushthread
void lua_pushthread (lua_State *L);
Empilha o fluxo de execuo representado por L na pilha. Retorna 1 se este fluxo de execuo for o fluxo de execuo principal do seu estado.
lua_pushvalue
void lua_pushvalue (lua_State *L, int index);
lua_pushvfstring
const char *lua_pushvfstring (lua_State *L, const char *fmt, va_list argp);
Equivalente a lua_pushfstring, exceto que esta funo recebe uma va_list ao invs de um nmero varivel de argumentos.
235
lua_rawequal
int lua_rawequal (lua_State *L, int index1, int index2);
Retorna 1 se os dois valores nos ndices aceitveis index1 e index2 forem iguais primitivamente (isto , sem fazer chamadas a metamtodos). Caso contrrio retorna 0. Tambm retorna 0 se qualquer um dos ndices no for vlido.
lua_rawget
void lua_rawget (lua_State *L, int index);
Similar a lua_gettable, mas faz um acesso primitivo (isto , sem usar metamtodos).
lua_rawgeti
void lua_rawgeti (lua_State *L, int index, int n);
Coloca na pilha o valor t[n], onde t o valor no ndice vlido fornecido. O acesso primitivo; isto , ele no invoca metamtodos.
lua_rawset
void lua_rawset (lua_State *L, int index);
Similar a lua_settable, mas faz uma atribuio primitiva (isto , sem usar metamtodos).
lua_rawseti
void lua_rawseti (lua_State *L, int index, int n);
Faz o equivalente a t[n] = v, onde t o valor no ndice vlido fornecido e v o valor no topo da pilha. Esta funo desempilha o valor da pilha. A atribuio primitiva; isto , ela no invoca metamtodos.
lua_Reader
typedef const char * (*lua_Reader) (lua_State *L, void *data, size_t *size);
A funo de leitura usada por lua_load. Toda vez que ela precisa de outro pedao do trecho, lua_load chama a funo de leitura, passando junto o seu parmetro data. A funo de leitura deve retornar um ponteiro para um bloco de memria com um novo pedao do trecho e atribuir a *size o tamanho do bloco. O bloco deve existir at que a funo de leitura seja chamada novamente. Para sinalizar o fim do trecho, a funo de leitura deve retornar NULL. A funo de leitura pode retornar pedaos de qualquer tamanho maior do que zero.
236
lua_register
void lua_register (lua_State *L, const char *name, lua_CFunction f);
Estabelece a funo C f como o novo valor da global name. Esta funo definida como uma macro:
#define lua_register(L,n,f) (lua_pushcfunction(L, f), lua_setglobal(L, n))
lua_remove
void lua_remove (lua_State *L, int index);
Remove o elemento no ndice vlido fornecido, deslocando para baixo os elementos acima deste ndice para preencher o buraco. Esta funo no pode ser chamada com um pseudo-ndice, visto que o pseudo-ndice no uma posio real da pilha.
lua_replace
void lua_replace (lua_State *L, int index);
Move o elemento do topo para a posio fornecida (e desempilha-o), sem deslocar qualquer elemento (substituindo portanto o valor na posio fornecida).
lua_resume
int lua_resume (lua_State *L, int narg);
Inicia e recomea uma co-rotina em um fluxo de execuo. Para iniciar uma co-rotina, deve-se primeiro criar um novo fluxo de execuo (ver lua_newthread); em seguida deve-se colocar na sua pilha a funo principal mais quaisquer argumentos; por ltimo chama-se lua_resume, com narg sendo o nmero de argumentos. Esta chamada retorna quando a co-rotina suspende ou finaliza sua execuo. Quando ela retorna, a pilha contm todos os valores passados para lua_yield ou todos os valores retornados pelo corpo da funo. lua_resume retorna LUA_YIELD se a co-rotina cede, 0 se a co-rotina termina sua execuo sem erros ou um cdigo de erro no caso de acontecerem erros (ver lua_pcall). No caso de erros, a pilha no desfeita, de forma que pode-se usar a API de depurao sobre ela. A mensagem de erro est no topo da pilha. Para reiniciar uma co-rotina, deve-se colocar na pilha dela somente os valores a serem passados como resultados de yield e ento chamar lua_resume.
lua_setallocf
void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);
Muda a funo de alocao de um dado estado para f com objeto userdata ud.
237
lua_setfenv
int lua_setfenv (lua_State *L, int index);
Desempilha uma tabela da pilha e estabelece esta tabela como sendo o novo ambiente para o valor no ndice fornecido. Se o valor no ndice fornecido no for nem uma funo, nem um fluxo de execuo nem um objeto userdata, lua_setfenv retorna 0. Caso contrrio a funo retorna 1.
lua_setfield
void lua_setfield (lua_State *L, int index, const char *k);
Faz o equivalente a t[k] = v, onde t o valor no ndice vlido fornecido e v o valor no topo da pilha. Esta funo desempilha o valor da pilha. Como em Lua, esta funo pode disparar um metamtodo para o evento "newindex" (ver B.2.9).
lua_setglobal
void lua_setglobal (lua_State *L, const char *name);
Desempilha um valor da pilha e o estabelece como o novo valor da global name. Esta funo definida como uma macro:
#define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, s)
lua_setmetatable
int lua_setmetatable (lua_State *L, int index);
Desempilha uma tabela da pilha e estabelece esta tabela como a nova metatabela para o valor no ndice aceitvel fornecido.
lua_settable
void lua_settable (lua_State *L, int index);
Faz o equivalente a t[k] = v, onde t o valor no ndice vlido fornecido, v o valor no topo da pilha e k o valor logo abaixo do topo. Esta funo desempilha tanto a chave como o valor da pilha. Da mesma forma que em Lua, esta funo pode disparar um metamtodo para o evento "newindex" (ver B.2.9).
lua_settop
void lua_settop (lua_State *L, int index);
Aceita qualquer ndice aceitvel, ou 0, e estabelece este ndice como o topo da pilha. Se o novo topo for maior do que o antigo, ento os novos elementos so preenchidos com nil. Se index for 0, ento todos os elementos da pilha so removidos.
238
lua_State
typedef struct lua_State lua_State;
Estrutura opaca que guarda o estado completo de um interpretador Lua. A biblioteca de Lua totalmente reentrante: no existem variveis globais. Toda a informao sobre um estado mantida nesta estrutura. Um ponteiro para este estado deve ser passado como o primeiro argumento para toda funo na biblioteca, exceto para lua_newstate, que cria um novo estado Lua a partir do zero.
lua_status
int lua_status (lua_State *L);
Retorna o status do fluxo de execuo L. O status pode ser 0 para um fluxo de execuo normal, um cdigo de erro se o fluxo de execuo terminar sua execuo com um erro ou LUA_YIELD se o fluxo de execuo estiver suspenso.
lua_toboolean
int lua_toboolean (lua_State *L, int index);
Converte um valor Lua no ndice aceitvel fornecido para um valor booleano C (0 ou 1). Como todos os testes em Lua, lua_toboolean retorna 1 para qualquer valor Lua diferente de false e de nil; caso contrrio a funo retorna 0. A funo tambm retorna 0 quando chamada com um ndice no vlido (se for desejado aceitar somente valores booleanos de fato, usar lua_isboolean para testar o tipo do valor).
lua_tocfunction
lua_CFunction lua_tocfunction (lua_State *L, int index);
Converte um valor no ndice aceitvel fornecido para uma funo C. Tal valor deve ser uma funo C; caso contrrio, retorna NULL.
lua_tointeger
lua_Integer lua_tointeger (lua_State *L, int idx);
Converte o valor Lua no ndice aceitvel fornecido para o tipo inteiro com sinal lua_Integer. O valor Lua deve ser um nmero ou uma cadeia que pode ser convertida para um nmero (ver B.2.3.2); caso contrrio, lua_tointeger retorna 0. Se o nmero no for um inteiro, ele truncado de alguma maneira no especificada.
239
lua_tolstring
const char *lua_tolstring (lua_State *L, int index, size_t *len);
Converte o valor Lua no ndice aceitvel fornecido para uma cadeia C. Se len no NULL, a funo tambm estabelece *len como o tamanho da cadeia. O valor Lua deve ser uma cadeia de caracteres ou um nmero; caso contrrio, a funo retorna NULL. Se o valor um nmero, ento lua_tolstring tambm muda o valor real na pilha para uma cadeia. (Esta mudana confunde lua_next quando lua_tolstring aplicada a chaves durante um percorrimento de tabela.) lua_tolstring retorna um ponteiro totalmente alinhado para uma cadeia de caracteres dentro do estado Lua. Esta cadeia sempre tem um zero ('\0') aps o seu ltimo caractere (como em C), mas pode conter outros zeros no seu corpo. Visto que Lua possui coleta de lixo, no h garantia de que o ponteiro retornado por lua_tolstring ser vlido aps o valor correspondente ser removido da pilha.
lua_tonumber
lua_Number lua_tonumber (lua_State *L, int index);
Converte o valor Lua no ndice aceitvel fornecido para o tipo C lua_Number (ver lua_Number). O valor Lua deve ser um nmero ou uma cadeia que pode ser convertida para um nmero (ver B.2.3.2); caso contrrio, lua_tonumber retorna 0.
lua_topointer
const void *lua_topointer (lua_State *L, int index);
Converte o valor no ndice aceitvel fornecido para um ponteiro C genrico (void*). O valor pode ser um objeto userdata, uma tabela, um fluxo de execuo ou uma funo; objetos diferentes iro fornecer ponteiros diferentes. No h maneira de converter o ponteiro de volta ao seu valor original. Tipicamente esta funo usada somente para informaes de depurao.
lua_tostring
const char *lua_tostring (lua_State *L, int index);
lua_tothread
lua_State *lua_tothread (lua_State *L, int index);
Converte o valor no ndice aceitvel fornecido para um fluxo de execuo (representado como lua_State*). Este valor deve ser um fluxo de execuo; caso contrrio, a funo retorna NULL.
240
lua_touserdata
void *lua_touserdata (lua_State *L, int index);
Se o valor no ndice aceitvel fornecido for um objeto userdata completo, a funo retorna o endereo do seu bloco. Se o valor for um userdata leve, a funo retorna seu ponteiro. Caso contrrio, retorna NULL.
lua_type
int lua_type (lua_State *L, int index);
Retorna o tipo do valor no ndice aceitvel fornecido ou LUA_TNONE para um ndice no vlido (isto , um ndice para uma posio da pilha "vazia"). Os tipos retornados por lua_type so codificados pelas seguintes constantes definidas em lua.h: LUA_TNIL, LUA_TNUMBER, LUA_TBOOLEAN, LUA_TSTRING, LUA_TTABLE, LUA_TFUNCTION, LUA_TUSERDATA, LUA_TTHREAD e LUA_TLIGHTUSERDATA.
lua_typename
const char *lua_typename (lua_State *L, int tp);
Retorna o nome do tipo codificado pelo valor tp, que deve ser um dos valores retornados por lua_type.
lua_Writer
typedef int (*lua_Writer) (lua_State *L, const void* p, size_t sz, void* ud);
O tipo da funo de escrita usada por lua_dump. Toda vez que ela produz outro pedao de trecho, lua_dump chama a funo de escrita, passando junto o buffer a ser escrito (p), seu tamanho (sz) e o parmetro data fornecido para lua_dump. A funo de escrita retorna um cdigo de erro: 0 significa nenhum erro; qualquer outro valor significa um erro e faz lua_dump parar de chamar a funo de escrita.
lua_xmove
void lua_xmove (lua_State *from, lua_State *to, int n);
Troca valores entre diferentes fluxos de execuo do mesmo estado global. Esta funo desempilha n valores da pilha from e os empilha na pilha to.
241
lua_yield
int lua_yield (lua_State *L, int nresults);
Cede uma co-rotina. Esta funo somente deve ser chamada como a expresso de retorno de uma funo C, como a seguir:
return lua_yield (L, nresults);
Quando uma funo C chama lua_yield desta maneira, a co-rotina sendo executada suspende a sua execuo e a chamada a lua_resume que iniciou esta co-rotina retorna. O parmetro results o nmero de valores da pilha que so passados como resultados para lua_resume.
lua_Debug
typedef struct lua_Debug { int event; const char *name; const char *namewhat; const char *what; const char *source; int currentline; int nups; int linedefined; int lastlinedefined; char short_src[LUA_IDSIZE]; /* private part */ ... } lua_Debug;
/* (n) */ /* (n) */ /* (S) */ /* (S) */ /* (l) */ /* (u) number of upvalues */ /* (S) */ /* (S) */ /* (S) */
Uma estrutura usada para guardar diferentes pedaos de informao sobre uma funo ativa. lua_getstack preenche somente a parte privada desta estrutura, para uso posterior. Para preencher os outros campos de lua_Debug com informao til, chamar lua_getinfo. Os campos de lua_Debug possuem o seguinte significado: source: se a funo foi definida em uma cadeia de caracters, ento source essa cadeia. Se a funo foi definida em um arquivo, ento source inicia com um '@' seguido pelo nome do arquivo; short_src: uma verso "adequada" para impresso de source, para ser usada em mensagens de erro; linedefined: o nmero da linha onde a definio da funo comea; lastlinedefined: o nmero da linha onde a definio da funo termina; what: a cadeia "Lua" se a funo uma funo Lua, "C" se ela uma funo C, "main" se ela a parte principal de um trecho e "tail" se ela foi uma funo que fez uma recurso final. No ltimo caso, Lua no possui nenhuma outra informao sobre a funo;
242
currentline: a linha corrente onde a funo fornecida est executando. Quando nenhuma informao sobre a linha est disponvel, atribui-se -1 a currentline; name: um nome razovel para a funo fornecida. Dado que funes em Lua so valores de primeira classe, elas no possuem um nome fixo: algumas funes podem ser o valor de mltiplas variveis globais, enquanto outras podem estar armazenadas somente em um campo de uma tabela. A funo lua_getinfo verifica como a funo foi chamada para encontrar um nome adequado. Se no possvel encontrar um nome, ento atribui-se NULL a name; namewhat: explica o campo name. O valor de namewhat pode ser "global", "local", "method", "field", "upvalue" ou "" (a cadeia vazia), de acordo com como a funo foi chamada (Lua usa a cadeia vazia quando nenhuma outra opo parece se aplicar); nups: o nmero de upvalues da funo.
lua_gethook
lua_Hook lua_gethook (lua_State *L);
lua_gethookcount
int lua_gethookcount (lua_State *L);
lua_gethookmask
int lua_gethookmask (lua_State *L);
lua_getinfo
int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);
Retorna informao sobre uma funo especfica ou uma invocao de funo especfica. Para obter informao sobre uma invocao de funo, o parmetro ar deve ser um registro de ativao vlido que foi preenchido por uma chamada anterior a lua_getstack ou foi fornecido como argumento para um gancho (ver lua_Hook). Para obter informao sobre uma funo deve-se coloc-la na pilha e iniciar a cadeia what com o caractere '>' (neste caso, lua_getinfo desempilha a funo no topo da pilha.) Por exemplo, para saber em qual linha uma funo f foi definida, pode-se escrever o seguinte cdigo:
lua_Debug ar; lua_getfield(L, LUA_GLOBALSINDEX, "f"); lua_getinfo(L, ">S", &ar); printf("%d\n", ar.linedefined); /* get global `f' */
243
Cada caractere na cadeia what seleciona alguns campos da estrutura ar para serem preenchidos ou um valor a ser empilhado na pilha: 'n': preenche os campos name e namewhat; 'S': preenche os campos source, short_src, linedefined, lastlinedefined e what; 'l': preenche o campo currentline; 'u': preenche o campo nups; 'f': coloca na pilha a funo que est executando no nvel fornecido; 'L': coloca na pilha uma tabela cujos ndices so o nmero das linhas que so vlidas na funo (uma linha vlida uma linha com algum cdigo associado, isto , uma linha onde pode-se colocar um ponto de parada. Linhas no vlidas incluem linhas vazias e comentrios).
Esta funo retorna 0 em caso de erro (por exemplo, no caso de uma opo invlida em what).
lua_getlocal
const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);
Obtm informao sobre uma varivel local de um registro de ativao fornecido. O parmetro ar deve ser um registro de ativao vlido que foi preenchido por uma chamada anterior a lua_getstack ou foi fornecido como um argumento para um gancho (ver lua_Hook). O ndice n seleciona qual varivel local inspecionar (1 o primeiro parmetro ou varivel local ativa e assim por diante, at a ltima varivel local ativa). lua_getlocal coloca o valor da varivel na pilha e retorna o nome dela. Nomes de variveis comeando com '(' (abre parnteses) representam variveis internas (variveis de controle de laos, temporrios e funes C locais.). Retorna NULL (e no empilha nada) quando o ndice maior do que o nmero de variveis locais ativas.
lua_getstack
int lua_getstack (lua_State *L, int level, lua_Debug *ar);
Obtm informao sobre a pilha de tempo de execuo do interpretador. Esta funo preenche partes de uma estrutura lua_Debug com uma identificao do registro de ativao da funo executando em um dado nvel. O nvel 0 a funo executando atualmente, ao passo que o nvel n+1 a funo que chamou o nvel n. Quando no h erros, lua_getstack retorna 1; quando chamada com um nvel maior do que a profundidade da pilha, a funo retorna 0.
244
lua_getupvalue
const char *lua_getupvalue (lua_State *L, int funcindex, int n);
Obtm informao sobre um upvalue de um fecho (para funes Lua, upvalues so variveis locais externas que a funo usa e que so conceitualmente includas no fecho dela). lua_getupvalue obtm o ndice n de um upvalue, coloca o valor do upvalue na pilha e retorna o nome dele. funcindex aponta para o fecho na pilha (upvalues no possuem uma ordem especfica, uma vez que eles so ativos ao longo de toda a funo. Ento, eles so numerados em uma ordem arbitrria). Retorna NULL (e no empilha nada) quando o ndice maior do que o nmero de upvalues. Para funes C, esta funo usa a cadeia vazia "" como um nome para todos os upvalues.
lua_Hook
typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);
O tipo para funes de gancho de depurao. Sempre que um gancho chamado, atribui-se ao campo event de seu argumento ar o evento especfico que disparou o gancho. Lua identifica estes eventos com a seguintes constantes: LUA_HOOKCALL, LUA_HOOKRET, LUA_HOOKTAILRET, LUA_HOOKLINE e LUA_HOOKCOUNT. Alm disso, para eventos de linha, o campo currentline tambm atribudo. Para obter o valor de qualquer campo em ar, o gancho deve chamar lua_getinfo. Para eventos de retorno, event pode ser LUA_HOOKRET, o valor normal, ou LUA_HOOKTAILRET. No ltimo caso, Lua est simulando um retorno de uma funo que fez uma recurso final; neste caso, intil chamar lua_getinfo. Enquanto Lua est executando um gancho, ela desabilita outras chamadas a ganchos. Portanto, se um gancho chama Lua de volta para executar uma funo ou um trecho, esta execuo ocorre sem quaisquer chamadas a ganchos.
lua_sethook
int lua_sethook (lua_State *L, lua_Hook func, int mask, int count);
Estabelece a funo de gancho de depurao. O argumento f uma funo de gancho. mask especifica sobre quais eventos o gancho ser chamado: ele formado por uma conjuno bit-a-bit das constantes LUA_MASKCALL, LUA_MASKRET, LUA_MASKLINE e LUA_MASKCOUNT. O argumento count somente possui significado quando a mscara inclui LUA_MASKCOUNT. Para cada evento, o gancho chamado como explicado abaixo: o gancho de chamada (CALL): chamado quando o interpretador chama uma funo. O gancho chamado logo aps Lua entrar na nova funo, antes da funo receber seus argumentos; o gancho de retorno (RET): chamado quando o interpretador retorna de uma funo. O gancho chamado logo aps Lua sair da funo. No se tem acesso aos valores a serem retornados pela funo; o gancho de linha (LINE): chamado quando o interpretador est para iniciar a execuo de uma nova linha de cdigo ou quando ele volta atrs no cdigo (mesmo que para a mesma linha) (este evento somente acontece quando Lua est executando uma funo Lua; o gancho do lua (COUNT): chamado aps o interpretador executar cada uma das instrues count (este evento somente ocorre quando Lua est executando uma funo Lua).
245
lua_setlocal
const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);
Estabelece o valor de uma varivel local de um registro de ativao fornecido. Os parmetros ar e n so como em lua_getlocal (ver lua_getlocal). lua_setlocal atribui o valor no topo da pilha varivel e retorna o nome dela. A funo tambm desempilha o valor da pilha. Retorna NULL (e no desempilha nada) quando o ndice maior do que o nmero de variveis locais ativas.
lua_setupvalue
const char *lua_setupvalue (lua_State *L, int funcindex, int n);
Estabelece o valor de um upvalue de um fecho. A funo atribui o valor no topo da pilha ao upvalue e retorna o nome dele. Ela tambm desempilha o valor da pilha. Os parmetros funcindex e n so como na funo lua_getupvalue (ver lua_getupvalue). Retorna NULL (e no desempilha nada) quando o ndice maior do que o nmero de upvalues.
luaL_addchar
void luaL_addchar (luaL_Buffer B, char c);
246
luaL_addlstring
void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);
Adiciona a cadeia de caracteres apontada por s com tamanho l ao buffer B (ver luaL_Buffer). A cadeia pode conter zeros dentro dela. luaL_addsize
void luaL_addsize (luaL_Buffer B, size_t n);
Adiciona ao buffer B (ver luaL_Buffer) uma cadeia de comprimento n copiada anteriormente para a rea de buffer (ver luaL_prepbuffer).
luaL_addstring
void luaL_addstring (luaL_Buffer *B, const char *s);
Adiciona a cadeia terminada por 0 apontada por s ao buffer B (ver luaL_Buffer). A cadeia no pode conter zeros dentro dela.
luaL_addvalue
void luaL_addvalue (luaL_Buffer *B);
Adiciona o valor no topo da pilha ao buffer B (ver luaL_Buffer). Desempilha o valor. Esta a nica funo sobre buffers de cadeias que deve ser chamada com um elemento extra na pilha, que o valor a ser adicionado ao buffer.
luaL_argcheck
void luaL_argcheck (lua_State *L, int cond, int numarg, const char *extramsg);
Verifica se cond verdadeira. Se no, dispara um erro com a seguinte mensagem, onde func recuperada a partir da pilha de chamada:
bad argument #<narg> to <func> (<extramsg>)
luaL_argerror
int luaL_argerror (lua_State *L, int numarg, const char *extramsg);
Dispara um erro com a seguinte mensagem, onde func recuperada a partir da pilha de chamada:
bad argument #<narg> to <func> (<extramsg>)
Esta funo nunca retorna, mas idiomtico us-la em funes C como return luaL_argerror(args).
247
luaL_Buffer
typedef struct luaL_Buffer luaL_Buffer;
O tipo para um buffer de cadeia de caracteres. Um buffer de cadeia permite cdigo C construir cadeias Lua pouco a pouco. O seu padro de uso o seguinte: primeiro declara-se uma varivel b do tipo luaL_Buffer; em seguida inicializa-se a varivel com uma chamada luaL_buffinit(L, &b); depois adiciona-se pedaos da cadeia ao buffer chamando qualquer uma das funes luaL_add*; termina-se fazendo uma chamada luaL_pushresult(&b). Esta chamada deixa a cadeia final no topo da pilha.
Durante essa operao normal, um buffer de cadeia usa um nmero varivel de posies da pilha. Ento, quando se est usando um buffer, no se deve assumir que sabe onde o topo da pilha est. Pode-se usar a pilha entre chamadas sucessivas s operaes de buffer desde que este uso seja balanceado; isto , quando se chama uma operao de buffer, a pilha est no mesmo nvel em que ela estava imediatamente aps a operao de buffer anterior (a nica exceo a esta regra luaL_addvalue). Aps chamar luaL_pushresult, a pilha est de volta ao seu nvel quando o buffer foi inicializado, mais a cadeia final no seu topo.
luaL_buffinit
void luaL_buffinit (lua_State *L, luaL_Buffer *B);
Inicializa um buffer B. Esta funo no aloca qualquer espao; o buffer deve ser declarado como uma varivel (ver luaL_Buffer).
luaL_callmeta
int luaL_callmeta (lua_State *L, int obj, const char *met);
Chama um metamtodo. Se o objeto no ndice obj possui uma metatabela e esta metatabela possui um campo e, esta funo chama esse campo e passa o objeto como seu nico argumento. Neste caso esta funo retorna 1 e coloca na pilha o valor retornado pela chamada. Se no h metatabela ou metamtodo, esta funo retorna 0 (sem empilhar qualquer valor na pilha). luaL_checkany
void luaL_checkany (lua_State *L, int narg);
Verifica se a funo tem um argumento de qualquer tipo (incluindo nil) na posio narg.
luaL_checkint
int luaL_checkint (lua_State *L, int narg);
Verifica se o argumento narg da funo um nmero e retorna este nmero convertido para um int.
248
luaL_checkinteger
lua_Integer luaL_checkinteger (lua_State *L, int narg);
Verifica se o argumento narg da funo um nmero e retorna este nmero convertido para um lua_Integer.
luaL_checklong
long luaL_checklong (lua_State *L, int narg);
Verifica se o argumento narg da funo um nmero e retorna este nmero convertido para um long.
luaL_checklstring
const char *luaL_checklstring (lua_State *L, int narg, size_t *l);
Verifica se o argumento narg da funo uma cadeia e retorna esta cadeia; se l no for NULL, preenche *l com o tamanho da cadeia.
luaL_checknumber
lua_Number luaL_checknumber (lua_State *L, int narg);
luaL_checkoption
int luaL_checkoption (lua_State *L, int narg, const char *def, const char *const lst[]);
Verifica se o argumento narg da funo uma cadeia e procura por esta cadeia no array lst (o qual deve ser terminado por NULL). Retorna o ndice no array onde a cadeia foi encontrada. Dispara um erro se o argumento no uma cadeia ou se a cadeia no pde ser encontrada. Se def no for NULL, a funo usa def como um valor padro quando no h argumento narg ou se este argumento for nil. Esta uma funo til para mapear cadeias para enumeraes de C (a conveno usual em bibliotecas Lua usar cadeias ao invs de nmeros para selecionar opes).
luaL_checkstack
void luaL_checkstack (lua_State *L, int sz, const char *msg);
Aumenta o tamanho da pilha para top + sz elementos, disparando um erro se a pilha no pode ser aumentada para aquele tamanho. msg um texto adicional a ser colocado na mensagem de erro.
249
luaL_checkstring
const char *luaL_checkstring (lua_State *L, int narg);
luaL_checktype
void luaL_checktype (lua_State *L, int narg, int t);
Verifica se o argumento narg da funo tem tipo t. Ver lua_type para a codificao de tipos para t.
luaL_checkudata
void *luaL_checkudata (lua_State *L, int narg, const char *tname);
Verifica se o argumento narg da funo um objeto userdata do tipo tname (ver luaL_newmetatable).
luaL_dofile
int luaL_dofile (lua_State *L, const char *filename);
luaL_dostring
void *luaL_checkudata (lua_State *L, int narg, const char *tname);
luaL_error
int luaL_error (lua_State *L, const char *fmt, ...);
Dispara um erro. O formato da mensagem de erro dado por fmt mais quaisquer argumentos extras, seguindo as mesmas regras de lua_pushfstring. Tambm adiciona no incio da mensagem o nome do arquivo e o nmero da linha onde o erro ocorreu, caso esta informao esteja disponvel. Esta funo nunca retorna, mas idiomtico us-la em funes C como return luaL_error(args).
250
luaL_getmetafield
int luaL_getmetafield (lua_State *L, int obj, const char *met);
Coloca na pilha o campo e da metatabela do objeto no ndice obj. Se o objeto no possui uma metatabela ou se a metatabela no possui este campo, retorna 0 e no empilha nada.
luaL_getmetatable
void luaL_getmetatable (lua_State *L, const char *tname);
Coloca na pilha a metatabela associada com o nome tname no registro (ver luaL_newmetatable).
luaL_gsub
const char *luaL_gsub (lua_State *L, const char *s, const char *p, const char *r);
Cria uma cpia da cadeia s substituindo qualquer ocorrncia da cadeia p pela cadeia r. Coloca a cadeia resultante na pilha e a retorna.
luaL_loadbuffer
int luaL_loadbuffer (lua_State *L, const char *buff, size_t sz, const char *name);
Carrega um buffer como um trecho de cdigo Lua. Esta funo usa lua_load para carregar o trecho no buffer apontado por buff com tamanho sz. Esta funo retorna os mesmos resultados de lua_load. name o nome do trecho, usado para informaes de depurao e mensagens de erro.
luaL_loadfile
int luaL_loadfile (lua_State *L, const char *filename);
Carrega um arquivo como um trecho de cdigo Lua. Esta funo usa lua_load para carregar o trecho no arquivo chamado filename. Se filename NULL, ento ela carrega a partir da entrada padro. A primeira linha no arquivo ignorada se ela comea com #. Esta funo retorna os mesmos resultados de lua_load, mas ela possui um cdigo de erro extra LUA_ERRFILE se ela no pode abrir/ler o arquivo. Da mesma forma que lua_load, esta funo somente carrega o trecho; ela no o executa.
251
luaL_loadstring
int luaL_loadstring (lua_State *L, const char *s);
Carrega uma cadeia como um trecho de cdigo Lua. Esta funo usa lua_load para carregar o trecho na cadeia (terminada por zero) s. Esta funo retorna os mesmos resultados de lua_load. Assim como lua_load, esta funo somente carrega o trecho; ela no o executa.
luaL_newmetatable
int luaL_newmetatable (lua_State *L, const char *tname);
Se o registro j possuir a chava tname, retorna 0. Caso contrrio, cria uma nova tabela para ser usada como uma metatabela para o objeto userdata, adiciona esta tabela ao registro com chave tname e retorna 1. Em ambos os casos coloca na pilha o valor final associado com tname no registro.
luaL_newstate
lua_State *luaL_newstate (void);
Cria um novo estado Lua. Chama lua_newstate com uma funo de alocao baseada na funo padro de C realloc e ento estabelece uma funo de pnico (ver lua_atpanic) que imprime uma mensagem de erro para a sada de erro padro em caso de erros fatais. Retorna o novo estado ou NULL se ocorreu um erro de alocao de memria.
luaL_openlibs
void luaL_openlibs (lua_State *L);
luaL_optint
int luaL_optint (lua_State *L, int narg, int d);
Se o argumento narg da funo for um nmero, retorna este nmero convertido para um int. Se este argumento estiver ausente ou se ele nil, retorna d. Caso contrrio, dispara um erro.
luaL_optinteger
lua_Integer luaL_optinteger (lua_State *L, int narg, lua_Integer d);
Se o argumento narg da funo for um nmero, retorna este nmero convertido para um lua_Integer. Se este argumento estiver ausente ou se ele nil, retorna d. Caso contrrio, dispara um erro.
252
luaL_optlong
long luaL_optlong (lua_State *L, int narg, long d);
Se o argumento narg da funo for um nmero, retorna este nmero convertido para um long. Se este argumento estiver ausente ou se ele nil, retorna d. Caso contrrio, dispara um erro.
luaL_optlstring
const char *luaL_optlstring (lua_State *L, int narg, const char *d, size_t *l);
Se o argumento narg da funo for uma cadeia, retorna esta cadeia. Se este argumento estiver ausente ou se ele for nil, retorna d. Caso contrrio, dispara um erro. Se l no for NULL, preenche a posio *l com o tamanho do resultado.
luaL_optnumber
lua_Number luaL_optnumber (lua_State *L, int narg, lua_Number d);
Se o argumento narg da funo for um nmero, retorna este nmero. Se este argumento estiver ausente ou se ele for nil, retorna d. Caso contrrio, dispara um erro.
luaL_optstring
const char *luaL_optstring (lua_State *L, int narg, const char *d);
Se o argumento narg da funo for uma cadeia, retorna esta cadeia. Se este argumento estiver ausente ou se ele for nil, retorna d. Caso contrrio, dispara um erro.
luaL_prepbuffer
char *luaL_prepbuffer (luaL_Buffer *B);
Retorna um endereo para um espao de tamanho LUAL_BUFFERSIZE onde se pode copiar uma cadeia para ser adicionada ao buffer B (ver luaL_Buffer). Aps copiar a cadeia para este espao deve-se chamar luaL_addsize com o tamanho da cadeia para adicion-la realmente ao buffer.
luaL_pushresult
void luaL_pushresult (luaL_Buffer *B);
253
luaL_ref
int luaL_ref (lua_State *L, int t);
Cria e retorna uma referncia, na tabela no ndice t, para o objeto no topo da pilha (e desempilha o objeto). Uma referncia uma chave inteira nica. Desde que no se adicione manualmente chaves inteiras na tabela t, luaL_ref garante a unicidade da chave que ela retorna. Pode-se recuperar um objeto referenciado pelo referncia r chamando lua_rawgeti(L, t, r). A funo luaL_unref libera uma referncia e o objeto associado a ela. Se o objeto no topo da pilha for nil, luaL_ref retorna a constante LUA_REFNIL. A constante LUA_NOREF garantidamente diferente de qualquer referncia retornada por luaL_ref.
luaL_Reg
typedef struct luaL_Reg { const char *name; lua_CFunction func; } luaL_Reg;
O tipo para arrays de funes a serem registrados por luaL_register. name o nome da funo e func um ponteiro para a funo. Qualquer array de luaL_Reg deve terminar com uma entrada sentinela na qual tanto name como func so NULL.
luaL_register
void luaL_register (lua_State *L, const char *libname, const luaL_Reg *l);
Abre uma biblioteca. Quando chamada com libname igual a NULL, simplesmente registra todas as funes na lista l (ver luaL_Reg) na tabela no topo da pilha. Quando chamada com um valor de libname diferente de NULL, luaL_register cria uma nova tabela t, estabelece ela como o valor da varivel global libname, estabelece ela como o valor de package.loaded[libname] e registra nela todas as funes na lista l. Se existir uma tabela em package.loaded[libname] ou na varivel libname, a funo reusa esta tabela ao invs de criar uma nova. Em qualquer caso a funo deixa a tabela no topo da pilha.
luaL_typename
const char *luaL_typename (lua_State *L, int idx);
254
luaL_typerror
int luaL_typerror (lua_State *L, int narg, const char *tname);
onde location produzida por luaL_where, func o nome da funo corrente e rt o nome do tipo do argumento.
luaL_unref
void luaL_unref (lua_State *L, int t, int ref);
Libera a referncia ref da tabela no ndice t (ver luaL_ref). A entrada removida da tabela, de modo que o objeto mencionado pode ser coletado. A referncia ref tambm liberada para ser usada novamente. Se ref for LUA_NOREF ou LUA_REFNIL, luaL_unref no faz nada.
luaL_where
void luaL_where (lua_State *L, int lvl);
Coloca na pilha uma cadeia identificando a posio atual do controle no nvel lvl na pilha de chamada. Tipicamente esta cadeia possui o seguinte formato:
chunkname:currentline:
Nvel 0 a funo executando correntemente, nvel 1 a funo que chamou a funo que est executando atualmente, etc. Esta funo usada para construir um prefixo para mensagens de erro.
B.5 Bibliotecas-padro
B.5.1 Viso geral
As bibliotecas-padro de Lua oferecem funes teis que so implementadas diretamente atravs da API C. Algumas dessas funes oferecem servios essenciais para a linguagem (por exemplo, type e getmetatable); outras oferecem acesso a servios "externos" (por exemplo, E/S); e outras poderiam ser implementadas em Lua mesmo, mas so bastante teis ou possuem requisitos de desemepenho crticos que merecem uma implementao em C (por exemplo, table.sort). Todas as bibliotecas so implementadas atrves da API C oficial e so fornecidas como mdulos C separados. Correntemente, Lua possui as seguintes bibliotecas-padro: biblioteca bsica; biblioteca de pacotes; manipulao de cadeias de caracteres;
255
manipulao de tabelas; funes matemticas (sen, log, etc.); entrada e sada; facilidades do sistema operacional; facilidades de depurao.
Excetuando-se a biblioteca bsica e a biblioteca de pacotes, cada biblioteca prov todas as suas funes como campos de uma tabela global ou como mtodos de seus objetos. Para ter acesso a essas bibliotecas, o programa hospedeiro C deve chamar a funo luaL_openlibs, que abre todas as bibliotecas padro. De modo alternativo, possvel abri-las individualmente, chamando luaopen_base (para a biblioteca bsica), luaopen_package (para a biblioteca de pacotes), luaopen_string (para a biblioteca de cadeias de caracteres), luaopen_table (para a biblioteca de tabelas), luaopen_math (para a biblioteca matemtica), luaopen_io (para a biblioteca de E/S), luaopen_os (para a biblioteca do Sistema Operacional), e luaopen_debug (para a biblioteca de depurao). Essas funes esto declaradas em lualib.h e no devem ser chamadas diretamente: deve-se cham-las como qualquer outra funo C de Lua, por exemplo, usando lua_call.
assert (v [, message]) Produz um erro quando o valor de seu argumento v falso (i.e., nil ou false); caso contrrio, retorna todos os seus argumentos. message uma mensagem de erro; quando ausente, a mensagem padro "assertion failed!"
collectgarbage (opt [, arg]) Esta funo uma interface genrica para o coletor de lixo. Ela realiza diferentes funes de acordo com o seu primeiro argumento, opt: stop : pra o coletor de lixo. restart : reinicia o coletor de lixo. collect : realiza um ciclo de coleta de lixo completo. count : retorna a memria total que est sendo usada por Lua (em Kbytes). step : realiza um passo de coleta de lixo. O "tamanho" do passo controlado por arg (valores maiores significam mais passos) de maneira no especificada. Se for desejado controlar o tamanho do passo, deve-se ajustar de maneira experimental o valor de arg. Retorna true se o passo terminou um ciclo de coleta de lixo. steppause : estabelece arg/100 como o novo valor para a pausa do coletor (ver B.2.11). setstepmul : estabelece arg/100 como o novo valor para o multiplicador de passo do coletor (ver B.2.11).
256
dofile (filename) Abre o arquivo indicado e executa o seu contedo como um trecho de cdigo Lua. Quando chamada sem argumentos, dofile executa o contedo da entrada padro (stdin). Retorna todos os valores retornados pelo trecho. Em caso de erros, dofile propaga o erro para o seu chamador (isto , dofile no executa em modo protegido).
error (message [, level]) Termina a ltima funo protegida chamada e retorna message como a mensagem de erro. A funo error nunca retorna. Geralmente, error adiciona alguma informao sobre a posio do erro no incio da mensagem. O argumento level especifica como obter a posio do erro. Quando ele igual a 1 (o padro), a posio do erro onde a funo error foi chamada. Quando ele 2, a posio do erro onde a funo que chamou error foi chamada; e assim por diante. Passando um valor 0 para level evita a adio de informao da posio do erro mensagem.
_G Uma varivel global (no uma funo) que armazena o ambiente global (isto , _G._G = _G). Lua por si s no usa esta varivel; uma modificao do seu valor no afeta qualquer ambiente e vice-versa. (usar setfenv para mudar ambientes.)
getfenv (f) Retorna o ambiente que est sendo usado correntemente pela funo. f pode ser uma funo Lua ou um nmero que especifica a funo naquele nvel de pilha: a funo que chamou getfenv possui nvel 1. Se a funo fornecida no uma funo Lua ou se f 0, getfenv retorna o ambiente global. O valor padro para f 1.
getmetatable (object) Se object no possuir uma metatabela, retorna nil. Caso contrrio, se a metatabela do objeto possuir um campo "__metatable", retorna o valor associado. Caso contrrio, retorna a metatabela do objeto fornecido.
ipairs (t) Retorna trs valores: uma funo iteradora, a tabela t e 0, de modo que a construo
for i,v in ipairs(t) do body end
ir iterar sobre os pares (1,t[1]), (2,t[2]), , at a primeira chave inteira ausente da tabela.
257
load (func [, chunkname]) Carrega um trecho usando a funo func para obter seus pedaos. Cada chamada a func deve retornar uma cadeia de caracteres que concatena com resultados anteriores. Quando func retorna nil (ou quando no retorna nenhum valor), isso indica o fim do trecho. Se no ocorrerem erros, retorna o trecho compilado como uma funo; caso contrrio, retorna nil mais a mensagem de erro. O ambiente da funo retornada o ambiente global. chunkname usado como o nome do trecho para mensagens de erro e informao de depurao. Quando ausente, o valor padro "=(load)".
loadfile ([filename]) Similar a load, mas obtm o trecho do arquivo filename ou da entrada padro, se nenhum nome de arquivo fornecido.
loadstring (string [, chunkname]) Similar a load, mas obtm o trecho da cadeia fornecida. Para carregar e rodar uma dada cadeia, usar a expresso idiomtica.
assert(loadstring(s))()
next (table [, index]) Permite a um programa pecorrer todos os campos de uma tabela. Seu primeiro argumento uma tabela e seu segundo argumento um ndice nesta tabela. next retorna o prximo ndice da tabela e seu valor associado. Quando chamada com nil como seu segundo argumento, next retorna um ndice inicial e seu valor associado. Quando chamada com o ltimo ndice ou com nil em uma tabela vazia, next retorna nil. Se o segundo argumento est ausente, ento ele interpretado como nil. Em particular, pode-se usar next(t) para verificar se a tabela est vazia. A ordem na qual os ndices so enumerados no especificada, at mesmo para ndices numricos (para percorrer uma tabela em ordem numrica, usar o for numrico ou a funo ipairs.). O comportamento de next indefinido se, durante o percorrimento, atribuir-se qualquer valor a um campo no existente na tabela. Pode-se, contudo, modificar campos existentes. Em particular, pode-se limpar campos existentes.
pairs (t) Retorna trs valores: a funo next, a tabela t e nil, de modo que a construo
for k,v in pairs(t) do body end
ir iterar sobre todos os pares chavevalor da tabela t. Ver a funo next para os cuidados que se deve ter ao modificar a tabela durante o seu percorrimento.
258
pcall (f, arg1, arg2, ...) Chama a funo f com os argumentos fornecidos em modo protegido. Isto significa que qualquer erro dentro de f no propagado; ao invs disso, pcall captura o erro e retorna um cdigo indicando o status. Seu primeiro resultado o cdigo de status (um booleano), que verdadeiro se a chamada aconteceu sem erros. Neste caso, pcall tambm retorna todos os resultados da chamada, depois deste primeiro resultado. No caso de acontecer um erro, pcall retorna false mais a mensagem de erro.
print (e1, e2, ...) Recebe qualquer nmero de argumentos e imprime os seus valores para stdout, usando a funo tostring para convert-los para cadeias de caracteres. print no projetada para sada formatada, mas somente como uma maneira rpida de mostrar um valor, tipicamente para depurao. Para sada formatada, usar string.format.
rawequal (v1, v2) Verifica se v1 igual a v2, sem invocar nenhum metamtodo. Retorna um booleano.
rawget (table, index) Obtm o valor real de table[index], sem invocar nenhum metamtodo. table deve ser uma tabela; index pode ser qualquer valor.
rawset (table, index, value) Atribui value como o valor real de table[index], sem invocar nenhum metamtodo. table deve ser uma tabela, index pode ser qualquer valor diferente de nil e value pode ser qualquer valor Lua. Essa funo retorna table.
select (index, ...) Se index for um nmero, retorna todos os argumentos aps o argumento nmero index. Caso contrrio, index deve ser a cadeia "#" e select retorna o nmero total de argumentos extras recebidos.
setfenv (f, table) Estabelece o ambiente a ser usado pela funo fornecida. f pode ser uma funo Lua ou um nmero que especifica a funo naquele nvel de pilha: a funo chamando setfenv possui nvel 1. setfenv retorna a funo fornecida. Como um caso especial, quando f 0 setfenv muda o ambiente do fluxo de execuo corrente. Neste caso, setfenv no retorna nenhum valor.
259
setmetatable (table, metatable) Estabelece a metatabela para a tabela fornecida (no se pode mudar a metatabela de outros tipos a partir de Lua, somente a partir de C.) Se metatable for nil, remove a metatabela da tabela fornecida. Se a metatabela original tiver um campo "__metatable", dispara um erro. Essa funo retorna table.
tonumber (obj [, base]) Tenta converter seu argumento para um nmero. Se o argumento j for um nmero ou uma cadeia de caracteres que pode ser convertida para um nmero, ento tonumber retorna este nmero; caso contrrio, retorna nil. Um argumento opcional especifica a base para interpretar o numeral. A base pode ser qualquer inteiro entre 2 e 36, inclusive. Em bases acima de 10, a letra 'A' (maiscula ou minscula) representa 10, 'B' representa 11 e assim por diante, com 'Z' representando 35. Na base 10 (o padro), o nmero pode ter uma parte decimal, bem como uma parte expoente opcional (ver B.2.2). Em outras bases, somente inteiros sem sinal so aceitos.
tostring (obj) Recebe um argumento de qualquer tipo e o converte para uma cadeia de caracteres em um formato razovel. Para um controle completo de como nmeros so convertidos, usar string.format. Se a metatabela de e possui um campo "__tostring", ento tostring chama o valor correspondente com e como argumento e usa o resultado da chamada como o seu resultado.
type (v) Retorna o tipo de seu nico argumento, codificado como uma cadeia de caracteres. Os resultados possveis desta funo so "nil" (uma cadeia de caracteres, no o valor nil), "number", "string", "boolean", "table", "function", "thread" e "userdata".
unpack (list [, i [, j]]) Retorna os elementos da tabela fornecida. Esta funo equivalente a
return list[i], list[i+1], , list[j]
exceto que o cdigo acima pode ser escrito somente para um nmero fixo de elementos. Por padro, i 1 e j o tamanho da lista, como definido pelo operador de tamanho (ver B.2.6.6).
_VERSION Uma varivel global (no uma funo) que armazena uma cadeia contendo a verso corrente do interpretador. O contedo corrente desta varivel "Lua 5.1".
260
xpcall (f, err) Esta funo similar a pcall, exceto que se pode estabelecer um novo tratador de erros. xpcall chama a funo f em modo protegido, usando err como um tratador de erros. Qualquer erro dentro de f no propagado; ao invs disso, xpcall captura o erro, chama a funo err com o objeto de erro original e retorna um cdigo indicando um status. Seu primeiro resultado o cdigo de status (um booleano), que verdadeiro se a chamada ocorreu sem erros. Neste caso, xpcall tambm retorna todos os resultados da chamada, depois deste primeiro resultado. Em caso de erro, xpcall retorna false mais o resultado de err.
coroutine.create (f) Cria uma nova co-rotina, com corpo f. f deve ser uma funo Lua. Retorna esta nova co-rotina, um objeto com tipo "thread".
coroutine.resume (co [, val1, ..., valn]) Inicia ou continua a execuo da co-rotina co. Na primeira vez que se "continua" uma co-rotina, ela comea executando o seu corpo. Os valores val1, so passados como os argumentos para o corpo da funo. Se a co-rotina j cedeu a execuo antes, resume a continua; os valores val1, so passados como os resultados da cesso. Se a co-rotina executa sem nenhum erro, resume retorna true mais quaisquer valores passados para yield (se a co-rotina cede) ou quaisquer valores retornados pelo corpo da funo (se a co-rotina termina). Se h qualquer erro, resume retorna false mais a mensagem de erro.
coroutine.running () Retorna a co-rotina sendo executada ou nil quando chamada pelo fluxo de execuo principal.
coroutine.status (co) Retorna o status da co-rotina co, como uma cadeia de caracteres: "running", se a co-rotina est executando (isto , ela chamou status); "suspended", se a co-rotina est suspensa em uma chamada a yield ou se ela no comeou a sua execuo ainda; "normal" se a co-rotina est ativa mas no est executando (isto , ela continuou outra co-rotina); e "dead" se a co-rotina terminou sua funo principal ou se ela parou com um erro. coroutine.wrap (f) Cria uma nova co-rotina, com corpo f. f deve ser uma funo Lua. Retorna uma funo que recomea a co-rotina cada vez que chamada. Quaisquer argumentos passados para a funo comportam-se como os argumentos extras para resume. Retorna os mesmos valores retornados por resume, exceto o primeiro booleano. Em caso de erro, propaga o erro.
261
coroutine.yield ([val1, ..., valn]) Suspende a execuo da co-rotina chamadora. A co-rotina no pode estar executando uma funo C, um metamtodo ou um iterador. Quaisquer argumentos para yield so passados como resultados extras para resume.
B.5.4 Mdulos
A biblioteca de pacotes prov facilidades bsicas para carregar e construir mdulos em Lua. Ela exporta duas de suas funes diretamente no ambiente global: require e module. Todas as outras funes so exportadas em uma tabela package.
module (name [, ...]) Cria um mdulo. Se h uma tabela em package.loaded[name], esta tabela o mdulo. Caso contrrio, se existe uma tabela global t com o nome fornecido, esta tabela o mdulo. Caso contrrio cria uma nova tabela t e a estabelece como o valor da global name e o valor de package.loaded[name]. Esta funo tambm inicializa t._NAME com o nome fornecido, t._M com o mdulo (o prprio t) e t._PACKAGE com o nome do pacote (o nome do mdulo completo menos o ltimo componente). Finalmente, module estabelece t como o novo ambiente da funo corrente e o novo valor de package.loaded[name], de modo que require retorna t. Se name for um nome composto (isto , um nome com componentes separados por pontos), module cria (ou reusa, se elas j existem) tabelas para cada componente. Por exemplo, se name a.b.c, ento module armazena a tabela do mdulo no campo c do campo b da global a. Esta funo pode receber algumas opes depois do nome do mdulo, onde cada opo uma funo a ser aplicada sobre o mdulo.
require (modname) Carrega o mdulo fornecido. Esta funo comea procurando na tabela package.loaded para determinar se modname j foi carregado. Em caso afirmativo, require retorna o valor armazenado em package.loaded[modname]. Caso contrrio, ela tenta achar um carregador para o mdulo. Para encontrar um carregador, require guiada pelo array package.loaders. Modificando este array, podemos mudar como require procura por um mdulo. A seguinte explicao baseada na configurao padro para package.loaders. Primeiro require consulta package.preload[modname]. Se existir um valor nesse campo, este valor (que deve ser uma funo) o carregador. Caso contrrio require busca por um carregador Lua usando o caminho armazenado em package.path. Se isso tambm falha, ela busca por um carregador C usando o caminho armazenado em package.cpath. Se isso tambm falha, ela tenta um carregador tudo-em-um (ver package.loaders). Uma vez que um carregador encontrado, require chama o carregador com um nico argumento, modname. Se o carregador retornar qualquer valor, require atribui o valor retornado a package.loaded[modname]. Se o carregador no retornar nenhum valor e no for atribudo nenhum valor a package.loaded[modname], ento require atribui true a esta posio. Em qualquer caso, require retorna o valor final de package.loaded[modname]. Se ocorrer um erro durante o carregamento ou a execuo do mdulo ou se no for possvel encontrar um carregador para o mdulo, ento require sinaliza um erro.
262
package.cpath O caminho usado por require para procurar por um carregador C. Lua inicializa o caminho C package.cpath da mesma forma que inicializa o caminho Lua package.path, usando a varivel de ambiente LUA_CPATH ou um caminho padro definido em luaconf.h.
package.loaded Uma tabela usada por require para controlar quais mdulos j foram carregados. Quando se requisita um mdulo modname e package.loaded[modname] no falso, require simplesmente retorna o valor armazenado l.
package.loaders Uma tabela usada por require para controlar como carregar mdulos. Cada posio nesta tabela uma funo buscadora. Quando est procurando um mdulo, require chama cada uma destas funes buscadoras em ordem crescente, com o nome do mdulo (o argumento fornecido a require) como seu nico parmetro. A funo pode retornar outra funo (o carregador do mdulo) ou uma cadeia de caracteres explicando porque ela no achou aquele mdulo (ou nil se ela no tem nada a dizer). Lua inicializa esta tabela com quatro funes. A primeira funo buscadora simplesmente procura um carregador no tabela package.preload. A segunda funo buscadora procura um carregador como uma biblioteca Lua, usando o caminho armazenado em package.path. Um caminho uma seqncia de padres separados por ponto-e-vrgulas. Para cada padro, a funo buscadora ir mudar cada ponto de interrogao no padro para filename, que o nome do mdulo com cada ponto substitudo por um "separador de diretrio" (como "/" no Unix); ento ela tentar abrir o nome do arquivo resultante. Por exemplo, se o caminho for a cadeia de caracteres
"./?.lua;./?.lc;/usr/local/?/init.lua"
a busca por um arquivo Lua para o mdulo foo tentar abrir os arquivos ./foo.lua, ./foo.lc e /usr/local/foo/init.lua, nessa ordem. A terceira funo buscadora procura um carregador como uma biblioteca C, usando o caminho fornecido pela varivel package.cpath. Por exemplo, se o caminho C a cadeia
"./?.so;./?.dll;/usr/local/?/init.so"
a funo buscadora para o mdulo foo tentar abrir os arquivos ./foo.so, ./foo.dll e /usr/local/foo/init.so, nessa ordem. Uma vez que ela encontra uma biblioteca C, esta funo buscadora primeiro usa uma facilidade de ligao dinmica para ligar a aplicao com a biblioteca. Ento ela tenta encontrar uma funo C dentro da biblioteca para ser usada como carregador. O nome desta funo C a cadeia "luaopen_" concatenada com uma cpia do nome do mdulo onde cada ponto substitudo por um sublinhado. Alm disso, se o nome do mdulo possui um hfen, seu prefixo at (e incluindo) o primeiro hfen removido. Por exemplo, se o nome do mdulo for a.v1-b.c, o nome da funo ser luaopen_b_c. A quarta funo buscadora tenta um carregador tudo-em-um. Ela procura no caminho C uma biblioteca para a raiz do nome do mdulo fornecido. Por exemplo, quando requisitando a.b.c, ela buscar por uma biblioteca C para a. Se encontrar, ela busca nessa biblioteca por uma funo de abertura para o submdulo; neste exemplo, seria luaopen_a_b_c. Com esta facilidade, um pacote pode empacotar vrios submdulos C dentro de uma nica biblioteca, com cada submdulo guardando a sua funo de abertura original.
263
package.loadlib (libname, funcname) Liga dinamicamente o programa hospedeiro com a biblioteca C libname. Dentro desta biblioteca, procura por uma funo funcname e retorna essa funo como uma funo C (desse modo, funcname deve seguir o protocolo (ver lua_CFunction)). Esta uma funo de baixo nvel. Ela contorna completamente o sistema de pacotes e de mdulos. Diferentemente de require, ela no realiza qualquer busca de caminho e no adiciona extenses automaticamente. libname deve ser o nome do arquivo completo da biblioteca C, incluindo se necessrio um caminho e uma extenso. funcname deve ser o nome exato exportado pela biblioteca C (que pode depender de como o compilador e o ligador C so usados). Esta funo no provida por ANSI C. Dessa forma, ela est disponvel somente em algumas plataformas (Windows, Linux, Mac OS X, Solaris, BSD, mais outros sistemas Unix que do suporte ao padro dlfcn).
package.path O caminho usado por require para buscar um carregador Lua. Ao iniciar, Lua inicializa esta varivel com o valor da varivel de ambiente LUA_PATH ou com um caminho padro definido em luaconf.h, se a varivel de ambiente no estiver definida. Qualquer ";;" no valor da varivel de ambiente ser substitudo pelo caminho padro.
package.preload Uma tabela para armazenar carregadores para mdulos especficos (ver require).
package.seeall (module) Estabelece uma metatabela para module com seu campo __index se referindo ao ambiente global, de modo que esse mdulo herda valores do ambiente global. Para ser usada como uma opo funo module.
string.byte (s [, i [, j]]) Retorna o cdigo numrico interno dos caracteres s[i], s[i+1], , s[j]. O valor padro para i 1; o valor padro para j i. Cdigos numricos no so necessariamente portveis entre plataformas.
264
string.char (i1, i2, ...) Recebe zero ou mais inteiros. Retorna uma cadeia com tamanho igual ao nmero de argumentos, na qual cada caractere possui um cdigo numrico interno igual ao seu argumento correspondente. Cdigos numricos no so necessariamente portveis entre plataformas.
string.dump (function) Retorna uma cadeia contendo a representao binria da funo fornecida, de modo que um loadstring posterior nesta cadeia retorna uma cpia da funo. function deve ser uma funo Lua sem upvalues.
string.find (s, pattern [, init [, plain]]) Procura o primeiro casamento do padro pattern na cadeia s. Se a funo acha um casamento, ento find retorna os ndices de s onde esta ocorrncia comeou e terminou; caso contrrio, retorna nil. O terceiro argumento, init, um valor numrico opcional e especifica onde iniciar a busca; seu valor padro 1 e pode ser negativo. Um valor true para o quarto argumento, plain, que opcional, desabilita as facilidades de casamento de padres, de modo que a funo faz uma operao "encontra subcadeia" simples, sem considerar nenhum caractere em pattern como "mgico". Se plain for fornecido, ento init deve ser fornecido tambm. Se o padro possuir capturas, ento em um casamento bem-sucedido os valores capturados so tambm retornados, aps os dois ndices.
string.format (formatstring, e1, e2, ...) Retorna a verso formatada de seu nmero varivel de argumentos seguindo a descrio dada no seu primeiro argumento (que deve ser uma cadeia). O formato da cadeia segue as mesmas regras da famlia printf de funes C padro. As nicas diferenas so que as opes/modificadores *, l, L, n, p e h no so oferecidas e que h uma opo extra, q. A opo q formata uma cadeia em uma forma adequada para ser lida de volta de forma segura pelo interpretador Lua; a cadeia escrita entre aspas duplas e todas as aspas duplas, quebras de linha, barras invertidas e zeros dentro da cadeia so corretamente escapados quando escritos. Por exemplo, a chamada
string.format('%q', 'a string with "quotes" and \n new line')
produzir a cadeia:
"a string with \"quotes\" and \ new line"
As opes c, d, E, e, f, g, G, i, o, u, X e x esperam um nmero como argumento, enquanto que q e s esperam uma cadeia. Esta funo no aceita valores de cadeias contendo zeros dentro delas, exceto quando esses valores so argumentos para a opo q.
265
string.gmatch (s, pattern) Retorna uma funo iteradora que, cada vez que chamada, retorna a prxima captura de pattern na cadeia s. Se pattern no especificar nenhuma captura, ento o casamento inteiro produzido a cada chamada. Como um exemplo, o seguinte lao
s = "hello world from Lua" for w in string.gmatch(s, "%a+") do print(w) end
ir iterar sobre todas as palavras da cadeia s, imprimindo uma por linha. O prximo exemplo coleta todos os pares key=value da cadeia fornecida e os coloca em uma tabela:
t = {} s = "from=world, to=Lua" for k, v in string.gmatch(s, "(%w+)=(%w+)") do t[k] = v end
Para essa funo, um '^' no incio de um padro no funciona como uma ncora, visto que isso iria impedir a iterao.
string.gsub (s, pattern, repl [, n]) Retorna uma cpia de s na qual todas as (ou as primeiras n, se fornecido) ocorrncias de pattern so substitudas por uma cadeia de substituio especificada por repl, que pode ser uma cadeia, uma tabela ou uma funo. gsub tambm retorna, como seu segundo valor, o nmero total de substituies que ocorreram. Se repl for uma cadeia, ento seu valor usado para a substituio. O caractere % funciona como um caractere de escape: qualquer seqncia em repl da forma %n, com n entre 1 e 9, representa o valor da n-sima subcadeia capturada. A seqncia %0 representa o casamento inteiro. A seqncia %% representa um % simples. Se repl for uma tabela, ento a tabela consultada a cada casamento, usando a primeira captura como a chave; se o padro no especifica nenhuma captura, ento o casamento inteiro usado como a chave. Se repl for uma funo, ento esta funo chamada toda vez que o casamento ocorre, com todas as subcadeias capturadas sendo passadas como argumentos, na ordem em que foram capturadas; se o padro no especificar nenhuma captura, ento o casamento inteiro passado como um nico argumento. Se o valor retornado pela consulta tabela ou pela chamada de funo for uma cadeia ou um nmero, ento esse valor usado como a cadeia de substituio; caso contrrio, se ele false ou nil, ento no h substituio (isto , o casamento original mantido na cadeia). Aqui esto alguns exemplos:
x = string.gsub("hello world", "(%w+)", "%1 %1") --> x="hello hello world world" x = string.gsub("hello world", "%w+", "%0 %0", 1) --> x="hello hello world" x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") --> x="world hello Lua from" x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) --> x="home = /home/roberto, user = roberto"
266
x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) return loadstring(s)() end) --> x="4+5 = 9" local t = {name="lua", version="5.1"} x = string.gsub("$name%-$version.tar.gz", "%$(%w+)", t) --> x="lua-5.1.tar.gz"
string.len (s) Recebe uma cadeia e retorna seu tamanho. A cadeia vazia "" tem tamanho 0. Zeros dentro da cadeia so contados, ento "a\000bc\000" possui tamanho 5.
string.lower (s) Recebe uma cadeia e retorna uma cpia desta cadeia com todas as letras maisculas convertidas para minsculas. Todos os demais caracteres permanecem iguais. A definio de o que uma letra maiscula depende do idioma (locale) corrente.
string.match (s, pattern [, init]) Procura o primeiro casamento de pattern na cadeia s. Se encontra um, ento match retorna as capturas do padro; caso contrrio retorna nil. Se pattern no especifica nenhuma captura, ento o casamento inteiro retornado. Um terceiro argumento numrico opcional, init, especifica onde iniciar a busca; seu valor padro 1 e pode ser negativo.
string.sub (s, i [, j]) Retorna uma subcadeia de s que inicia em i e continua at j; i e j podem ser negativos. Se j est ausente, ento assume-se que ele igual a -1 (que o mesmo que o tamanho da cadeia). Em particular, a chamada string.sub(s,1,j) retorna um prefixo de s com tamanho j e string.sub(s, -i) retorna um sufixo de s com tamanho i.
string.upper (s) Recebe uma cadeia e retorna uma cpia desta cadeia com todas as letras minsculas convertidas para maisculas. Todos os demais caracteres permanecem iguais. A definio de o que uma letra minscula depende do idioma (locale) corrente.
267
B.5.6 Padres
Uma classe de caracteres usada para representar um conjunto de caracteres. As seguintes combinaes so permitidas em descries de uma classe de caracteres: x: (onde x no um dos caracteres mgicos ^$()%.[]*+-?) representa o prprio caractere x. . : (um ponto) representa todos os caracteres. %a: representa todas as letras. %c: representa todos os caracteres de controle. %d: representa todos os dgitos. %l: representa todas as letras minsculas. %p: representa todos os caracteres de pontuao. %s: representa todos os caracteres de espao. %u: representa todas as letras maisculas. %w: representa todos os caracteres alfanumricos. %x: representa todos os dgitos hexadecimais. %z: representa o caractere com representao 0. %x: (onde x qualquer caractere no-alfanumrico) representa o caractere x. Esta a maneira padro de escapar os caracteres mgicos. Qualquer caractere de pontuao (at mesmo os no mgicos) pode ser precedido por um '%' quando usado para representar a si mesmo em um padro. [set]: representa a classe que a unio de todos os caracteres em set. Uma faixa de caracteres pode ser especificada separando os caracteres finais da faixa com um '-'. Todas as classes %x descritas acima tambm podem ser usadas como componentes em set. Todos os outros caracteres em set representam eles mesmos. Por exemplo, [%w_] (ou [_%w]) representa todos os caracteres alfanumricos mais o sublinhado, [0-7] representa os dgitos octais e [0-7%l%-] representa os dgitos octais mais as letras minsculas mais o caractere '-'. A interao entre faixas e classes no definida. Portanto, padres como [%a-z] ou [a-%%] no possuem significado. [^set] : representa o complemento de set, onde set interpretado como acima.
Para todas as classes representadas por uma nica letra (%a, %c etc.), a letra maiscula correspondente representa o complemento da classe. Por exemplo, %S representa todos os caracteres que no so de espao. As definies de letra, espao e outros grupos de caracteres dependem do idioma (locale) corrente. Em particular, a classe [a-z] pode no ser equivalente a %l.
268
Um item de padro pode ser: uma classe de um nico caractere, que casa qualquer caractere simples que pentena classe; uma classe de um nico caractere seguida por '*', que casa 0 ou mais repeties de caracteres da classe. Estes itens de repetio sempre casaro a maior seqncia possvel; uma classe de um nico caractere seguida por '+', que casa 1 ou mais repeties de caracteres da classe. Estes itens de repetio sempre casaro a maior seqncia possvel; uma classe de um nico caractere seguida por '-', que tambm casa 0 ou mais repeties de caracteres da classe. Diferentemente de '*', estes itens de repetio sempre casaro a menor seqncia possvel; uma classe de um nico caractere seguida por '?', que casa 0 ou 1 ocorrncia de um caractere da classe; %n, para n entre 1 e 9; tal item casa uma subcadeia igual n-sima cadeia capturada; %bxy, onde x e y so dois caracteres distintos; tal item casa cadeias que comeam com x, terminam com y e onde o nmero de xs e de ys balanceado. Isto significa que, se algum ler a cadeia da esquerda para a direita, contando +1 para um x e -1 para um y, o y final o primeiro y onde o contador alcana 0. Por exemplo, o item %b() casa expresses com parnteses balanceados.
Um padro uma seqncia de itens de padro. Um '^' no incio de um padro ancora o casamento no incio da cadeia sendo usada. Um '$' no fim de um padr ancora o casamento no fim da cadeia sendo usada. Em outras posies, '^' e '$' no possuem significado especial e representam a si mesmos. Um padro pode conter subpadres delimitados por parnteses; eles descrevem capturas. Quando um casamento ocorre, as subcadeias da cadeia sendo usada que casaram com as capturas so armazenadas (capturadas) para uso futuro. Capturas so numeradas de acordo com os seus parnteses esquerdos. Por exemplo, no padro "(a*(.)%w(%s*))", a parte da cadeia casando "a*(.)%w(%s*)" armazenada como a primeira captura (e portanto tem nmero 1); o caractere casando "." capturado com o nmero 2 e a parte casando "%s*" possui nmero 3. Como um caso especial, a captura vazia () captura a posio da cadeia corrente (um nmero). Por exemplo, se for aplicado o padro "()aa()" na cadeia "flaaap", haver duas capturas: 3 e 5. Um padro no pode conter zeros dentro dele. Usar %z como alternativa.
table.concat (table [, sep [, i [, j]]]) Dado um array onde todos os elementos so cadeias ou nmeros, retorna table[i]..sep..table[i+1] sep..table[j]. O valor padro para sep a cadeia vazia, o padro para i 1 e o padro para j o tamanho da tabela. Se i for maior do que j, retorna a cadeia vazia.
269
table.insert (table, [pos,] value) Insere o elemento value na posio pos de table, deslocando os outros elementos para abrir espao, se necessrio. O valor padro para pos n+1, onde n o tamanho da tabela (ver B.2.6.6), de modo que uma chamada table.insert(t,x) insere x no fim da tabela t.
table.maxn (table) Retorna o maior ndice numrico positivo da tabela fornecida ou zero se a tabela no possuir ndices numricos positivos (para realizar seu trabalho esta funo faz um percorrimento linear da tabela inteira).
table.remove (table [, pos]) Remove de table o elemento na posio pos, deslocando os outros elementos para preencher o espao, se necessrio. Retorna o valor do elemento removido. O valor padro para pos n, onde n o tamanho da tabela, de modo que uma chamada table.remove(t) remove o ltimo elemento da tabela t.
table.sort (table [, comp]) Ordena os elementos da tabela em uma dada ordem, in-place, de table[1] at table[n], onde n o tamanho da tabela. Se comp fornecido, ento ele deve ser uma funo que recebe dois elementos da tabela e retorna true quando o primeiro menor do que o segundo (de modo que not comp(a[i+1],a[i]) ser verdadeiro aps a ordenao). Se comp no fornecido, ento o operador padro de Lua < usado em seu lugar. O algoritmo de ordenao no estvel; isto , elementos considerados iguais pela ordem fornecida podem ter suas posies relativas trocadas pela ordenao.
270
math.atan2 (x) Retorna o arco tangente de y/x (em radianos), mas usa o sinal dos dois parmetros para achar o quadrante do resultado (tambm trata corretamente o caso de x ser zero).
math.frexp (x) Retorna m e e tais que x = m2e, e um inteiro e o valor absoluto de m est no intervalo [0.5, 1) (ou zero quando x zero).
271
math.huge (x) O valor de HUGE_VAL, um valor maior ou igual a qualquer outro valor numrico.
math.pow (x, y) Retorna xy (tambm pode-se usar a expresso x^y para computar este valor).
272
math.random ([m [,n]]) Esta funo uma interface para a funo geradora pseudo-randmica simples rand fornecida por ANSI C (nenhuma garantia pode ser dada para suas propriedades estatsticas). Quando chamada sem argumentos, retorna um nmero real pseudo-randmico no intervalo [0,1). Quando chamada com um nmero m, math.random retorna um inteiro pseudo-randmico no intervalo [1, m). Quando chamada com dois nmeros m e n, math.random retorna um inteiro pseudo-randmico no intervalo [m, n).
math.randomseed (x) Estabelece x como a "semente" para o gerador pseudo-randmico: sementes iguais produzem seqncias iguais de nmeros.
math.sqrt (x) Retorna a raiz quadrada de x (tambm se pode usar a expresso x^0.5 para computar este valor).
273
io.close ([file]) Equivalente a file:close(). Quando no recebe file, fecha o arquivo de sada padro.
io.input ([file]) Quando chamada com um nome de arquivo, abre o arquivo com aquele nome (em modo texto) e estabelece seu manipulador como o arquivo de entrada padro. Quando chamada com um manipulador de arquivo, simplesmente estabelece este manipulador de arquivo como o arquivo de entrada padro. Quando chamada sem parmetros, retorna o arquivo de entrada padro corrente. Em caso de erros esta funo dispara o erro, ao invs de retornar um cdigo de erro.
io.lines ([filename]) Abre o nome de arquivo fornecido em modo de leitura e retorna uma funo iteradora que, cada vez que chamada, retorna uma nova linha do arquivo. Portanto, a construo
for line in io.lines(filename) do body end
ir iterar sobre todas as linhas do arquivo. Quando a funo iteradora detecta o fim do arquivo, ela retorna nil (para finalizar o lao) e automaticamente fecha o arquivo. A chamada io.lines() (sem nenhum nome de arquivo) equivalente a io.input():lines(); isto , ela itera sobre as linhas do arquivo de entrada padro. Neste caso ela no fecha o arquivo quando o lao termina.
274
io.open (filename [, mode]) Esta funo abre um arquivo, no modo especificado na cadeia mode. Ela retorna um novo manipulador de arquivo ou, em caso de erros, nil mais uma mensagem de erro. A cadeia de caracteres mode pode ser qualquer uma das seguintes: r: modo de leitura (o padro); w: modo de escrita; a: modo de adio; r+: modo de atualizao, todos os dados anteriores so preservados; w+: modo de atualizao, todos os dados anteriores so preservados; a+: modo de atualizao de adio, dados anteriores so preservados, a escrita somente permitida no fim do arquivo.
A cadeia mode tambm pode ter um 'b' no fim, que necessrio em alguns sistemas para abrir o arquivo em modo binrio. Esta cadeia exatamente o que usado na funo padro de C fopen.
io.output ([file]) Similar a io.input, mas opera sobre o arquivo de sada padro.
io.popen ([prog [, mode]]) Inicia o programa prog em um processo separado e retorna um manipulador de arquivo que pode ser usado para ler dados deste programa (se mode "r", o padro) ou escrever dados para este programa (se mode "w"). Esta funo dependente do sistema e no est disponvel em todas as plataformas.
io.tmpfile () Retorna um manipulador para um arquivo temporrio. Este arquivo aberto em modo de atualizao e automaticamente removido quando o programa termina.
io.type (obj) Verifica se obj um manipulador de arquivo vlido. Retorna a cadeia "file" se obj um manipulador de arquivo aberto, "close file" se obj um manipulador de arquivo fechado ou nil se obj no um manipulador de arquivo.
275
file:close () Fecha file. Arquivos so automaticamente fechados quando seus manipuladores so coletados pelo coletor de lixo, mas leva uma quantidade indeterminada de tempo para isso acontecer.
file:lines () Retorna uma funo iteradora que, cada vez que chamada, retorna uma nova linha do arquivo. Portanto, a construo
for line in file:lines() do ... end
ir iterar sobre todas as linhas do arquivo (ao contrrio de io.lines, essa funo no fecha o arquivo quando o lao termina).
file:read (format1, ...) L o arquivo file, de acordo com os formatos fornecidos, os quais especificam o que deve ser lido. Para cada formato, a funo retorna uma cadeia (ou um nmero) com os caracteres lidos ou nil se ela no pode retornar dados com o formato especificado. Quando chamada sem formatos, ela usa o formato padro que l a prxima linha toda. Os formatos disponveis so: *n: l um nmero; este o nico formato que retorna um nmero ao invs de uma cadeia. *a: l o arquivo inteiro, iniciando na posio corrente. Quando est no final do arquivo, retorna a cadeia vazia. *l: l a prxima linha (pulando o fim de linha), retornando nil ao final do arquivo. Este o formato padro. nmero: l uma cadeia at este nmero de caracteres, retornando nil ao final do arquivo. Se o nmero fornecido zero, a funo no l nada e retorna uma cadeia vazia ou nil quando est no fim do arquivo.
276
file:seek ([whence] [, offset]) Estabelece e obtm a posio do arquivo, medida a partir do incio do arquivo, at a posio dada por offset mais uma base especificada pela cadeia whence, como a seguir: set : base a posio 0 (o incio do arquivo); cur : base a posio corrente; end" : base o fim do arquivo;
Em caso de sucesso, a funo seek retorna a posio final do arquivo, medida em bytes a partir do incio do arquivo. Se esta funo falhar, ela retorna nil, mais uma cadeia descrevendo o erro. O valor padro para whence "cur" e para offset 0. Portanto, a chamada file:seek() retorna a posio do arquivo corrente, sem modific-la; a chamada file:seek("set") estabelece a posio para o incio do arquivo (e retorna 0); e a chamada file:seek("end") estabelece a posio para o fim do arquivo e retorna seu tamanho.
file:setvbuf (mode [, size]) Define o modo de bufferizao para um arquivo de sada. H trs modos disponveis: no : nenhuma bufferizao; o resultado de qualquer operao de sada aparece imediatamente; full : bufferizao completa; a operao de sada realizada somente quando o buffer est cheio (ou quando explicitamente se descarrega o arquivo (ver io.flush)); line : bufferizao de linha; a sada bufferizada at que uma nova linha produzida ou h qualquer entrada a partir de alguns arquivos especiais (como um dispositivo de terminal).
Para os ltimos dois casos, size especifica o tamanho do buffer, em bytes. O padro um tamanho apropriado.
file:write (value1, ...) Escreve o valor de cada um de seus argumentos para file. Os argumentos devem ser cadeias de caracteres ou nmeros. Para escrever outros valores, usar tostring ou string.format antes de write.
os.clock () Retorna uma aproximao da quantidade de tempo de CPU, em segundos, usada pelo programa.
277
os.date ([format [, time]]) Retorna uma cadeia ou uma tabela contendo data e hora, formatada de acordo com a cadeia format fornecida. Se o argumento time estiver presente, este o tempo a ser formatado (ver a funo os.time para uma descrio deste valor). Caso contrrio, date formata a hora corrente. Se format comear com '!', ento a data formatada no Tempo Universal Coordenado. Aps esse caractere opcional, se format a cadeia "*t", ento date retorna uma tabela com os seguintes campos: year (quatro dgitos), month (1--12), day (1--31), hour (0--23), min (0--59), sec (0--61), yday (dia do ano) e isdst (flag que indica o horrio de vero, um booleano). Se format no for "*t", ento date retorna a data como uma cadeia de caracteres, formatada de acordo com as mesmas regras da funo C strftime. Quando chamada sem argumentos, date retorna uma representao aceitvel da data e da hora que depende do sistema hospedeiro e do idioma (locale) corrente. (isto , os.date() equivalente a os.date("%c")).
os.difftime (t2, t1) Retorna o nmero de segundos a partir do tempo t1 at o tempo t2. Em POSIX, Windows e alguns outros sistemas, este valor exatamente t2-t1.
os.execute ([command]) Esta funo equivalente funo C system. Ela passa command para ser executado por um interpretador de comandos do sistema operacional. Ela retorna um cdigo de status, que dependente do sistema. Se command estiver ausente, ento a funo retorna um valor diferente de zero se um interpretrador de comandos estiver disponvel e zero caso contrrio.
os.exit ([code]) Chama a funo C exit, com um cdigo code opcional, para terminar o programa hospedeiro. O valor padro para code o cdigo de sucesso.
os.getenv (varname) Retorna o valor da varivel de ambiente do processo varname ou nil se a varivel no estiver definida.
os.remove (filename) Remove um arquivo ou diretrio com o nome fornecido. Diretrios devem estar vazios para serem removidos. Se esta funo falhar, ela retorna nil, mais uma cadeia descrevendo o erro.
278
os.rename (oldname, newname) Renomeia um arquivo ou diretrio chamado oldname para newname. Se esta funo falhar, ela retorna nil, mais uma cadeia descrevendo o erro.
os.setlocale (locale [, category]) Estabelece o idioma (locale) corrente do programa. locale uma cadeia de caracteres especificando um idioma; category uma cadeia opcional descrevendo para qual categoria deve-se mudar: "all", "collate", "ctype", "monetary", "numeric" ou "time"; a categoria padro "all". Esta funo retorna o nome do novo idioma ou nil se a requisio no pode ser honrada. Se locale for a cadeia vazia, estabelece-se o idioma corrente como um idioma nativo definido pela implementao. Se locale for a cadeia "C", estabelece-se o idioma corrente como o idioma padro de C. Quando chamada com nil como o primeiro argumento, esta funo retorna somente o nome do idioma corrente para a categoria fornecida.
os.time ([table]) Retorna o tempo corrente quando chamada sem argumentos ou um tempo representando a data e a hora especificados pela tabela fornecida. Esta tabela deve ter campos year, month e day e pode ter campos hour, min, sec e isdst (para uma descrio destes campos, ver a funo os.date). O valor retornado um nmero, cujo significado depende do seu sistema. Em POSIX, Windows e alguns outros sistemas, este nmero conta o nmero de segundos desde algum tempo de incio dado (a "era"). Em outros sistemas, o significado no especificado e o nmero retornado por time pode ser usado somente como um argumento para date e difftime.
os.tmpname () Retorna uma cadeia de caracteres com o nome de um arquivo que pode ser usado para um arquivo temporrio. O arquivo deve ser explicitamente aberto antes de ser usado e explicitamente removido quando no for mais necessrio.
279
debug.debug () Entra em um modo interativo com o usurio, executando cada cadeia de caracteres que o usurio entra. Usando comandos simples e outros mecanismos de depurao, o usurio pode inspecionar variveis globais e locais, mudar o valor delas, avaliar expresses, etc. Uma linha contendo somente a palavra cont termina esta funo, de modo que a funo chamadora continua sua execuo. Os comandos para debug.debug no so aninhados de modo lxico dentro de nenhuma funo e, portanto, no possuem acesso direto a variveis locais.
debug.gethook () Retorna as configuraes de gancho correntes do fluxo de execuo como trs valores: a funo de gancho corrente, a mscara de ganho corrente e a contagem de ganho corrente (como estabelecido pela funo debug.sethook).
debug.getinfo (function [, what]) Retorna uma tabela com informao sobre uma funo. Pode-se fornecer a funo diretamente ou pode-se fornecer um nmero como o valor de function, que significa a funo executando no nvel function da pilha de chamadas do fluxo de execuo fornecido: nvel 0 a funo corrente (a prpria getinfo); nvel 1 a funo que chamou getinfo; e assim por diante. Se function um nmero maior do que o nmero de funes ativas, ento getinfo retorna nil. A tabela retornada pode conter todos os campos retornados por lua_getinfo, com a cadeia what descrevendo quais campos devem ser preenchidos. O padro para what obter todas as informaes disponveis, exceto a tabela de linhas vlidas. Se presente, a opo 'f' adiciona um campo chamado func com a prpria funo. Se presente, a opo 'L' adiciona um campo chamado activelines com a tabela de linhas vlidas. Por exemplo, a expresso debug.getinfo(1,"n").name retorna uma tabela com um nome para a funo corrente, se um nome razovel pode ser encontrado, e a expresso debug.getinfo(print) retorna uma tabela com todas as informaes disponveis sobre a funo print.
debug.getlocal (level, local) Esta funo retorna o nome e o valor da varivel local com ndice local da funo no nvel level da pilha (o primeiro parmetro ou varivel local possui ndice 1 e assim por diante, at a ltima varivel local ativa). A funo retorna nil se no existe uma varivel local com o ndice fornecido e dispara um erro quando chamada com um level fora da faixa de valores vlidos (pode-se chamar debug.getinfo para verificar se o nvel vlido). Nomes de variveis que comeam com '(' (abre parnteses) representam variveis internas (variveis de controle de laos, temporrios e locais de funes C).
280
debug.getmetatable (object) Retorna a metatabela do object fornecido ou nil se ele no possui uma metatabela.
debug.getupvalue (func, up) Esta funo retorna o nome e o valor do upvalue com ndice up da funo func. A funo retorna nil se no h um upvalue com o ndice fornecido.
debug.setfenv (object, table) Estabelece a tabela table como o ambiente do object fornecido. Retorna object.
debug.sethook (hook, mask [, count]) Estabelece a funo fornecida como um gancho. A cadeia mask e o nmero count descrevem quando o gancho ser chamado. A cadeia mask pode ter os seguintes caracteres, com o respectivo significado: "c" : o gancho chamado toda vez que Lua chama uma funo; "r" : o gancho chamado toda vez que Lua retorna de uma funo; "l" : o gancho chamado toda vez que Lua entra uma nova linha de cdigo.
Com um count diferente de zero, o gancho chamado aps cada count instrues. Quando chamada sem argumentos, debug.gethook desabilita o gancho. Quando o gancho chamado, seu primeiro parmetro uma cadeia de caracteres descrevendo o evento que disparou a sua chamada: "call", "return" (ou "tail return"), "line" e "count". Para eventos de linha, o gancho tambm obtm o novo nmero de linha como seu segundo parmetro. Dentro do gancho, possvel chamar getinfo com nvel 2 para obter mais informao sobre a funo sendo executada (nvel 0 a funo getinfo e nvel 1 a funo de gancho), a menos que o evento seja "tail return". Neste caso, Lua est somente simulando o retorno e uma chamada a getinfo retornar dados invlidos.
debug.setlocal (level, local, value) Esta funo atribui o valor value varivel local com ndice local da funo no nvel level da pilha. A funo retorna nil se no h uma varivel local com o ndice fornecido e dispara um erro quando chamada com um level fora da faixa de valores vlidos (pode-se chamar getinfo para verificar se o nvel vlido). Caso contrrio, a funo retorna o nome da varivel local.
281
debug.setmetatable (object, table) Estabelece table como a metatabela do object fornecido (table pode ser nil). debug.setupvalue (func, up, value) Esta funo atribui o valor value ao upvalue com ndice up da funo func. A funo retorna nil se no h um upvalue com o ndice fornecido. Caso contrrio, a funo retorna o nome do upvalue.
debug.traceback ([message]) Retorna uma cadeia de caracteres com um trao da pilha de chamadas. Uma cadeia opcional message adicionada ao incio do trao. Um nmero opcional level diz em qual nvel iniciar o trao (o padro 1, a funo chamando traceback).
As opes so: -e stat : executa a cadeia stat; -l mod : "requisita" mod; -i : entra em modo interativo aps executar script; -v : imprime informao de verso; -- : pra de tratar opes; - : executa stdin como um arquivo e pra de tratar opes.
Aps tratar suas opes, Lua executa o script fornecido, passando para ele os args fornecidos como cadeias de argumentos. Quando chamado sem argumentos, lua comporta-se como lua -v -i quando a entrada padro (stdin) um terminal e como lua - em caso contrrio. Antes de executar qualquer argumento, o interpretador verifica se h uma varivel de ambiente LUA_INIT. Se seu formato @filename, ento lua executa o arquivo. Caso contrrio, lua executa a prpria cadeia de caracteres. Todas as opes so manipuladas na ordem dada, exceto -i. Por exemplo, uma invocao como
$ lua -e'val=1' -e 'print(val)' script.lua
ir primeiro atribuir 1 a a, depois imprimir o valor de a (que '1') e finalmente executar o arquivo script.lua sem argumentos (aqui $ o prompt do interpretador de comandos. Pode-se ter um prompt diferente).
282
Antes de comear a executar o script, lua guarda todos os argumentos fornecidos na linha de comando em uma tabela global chamada arg. O nome do script armazenado no ndice 0, o primeiro argumento aps o nome do script fica no ndice 1 e assim por diante. Quaisquer argumentos antes do nome do script (isto , o nome do interpretador mais as opes) ficam em ndices negativos. Por exemplo, na chamada
$ lua -la b.lua t1 t2
e finalmente executa o arquivo b.lua. O script chamado com arg[1], arg[2], como argumentos; ele tambm pode acessar estes argumentos com a expresso vararg '...'. Em modo interativo, se for escrito um comando incompleto, o interpretador espera que o complete e indica isto atravs de um prompt diferente. Se a varivel global _PROMPT contiver uma cadeia de caracteres, ento o seu valor De maneira similar, se a varivel global _PROMPT2 contm uma cadeia, seu valor secundrio (mostrado durante comandos incompletos). Portanto, os dois prompts diretamente na linha de comando ou em quaisquer programas Lua fazendo uma Ver o exemplo a seguir:
$ lua -e"_PROMPT='myprompt> '" i
usado como o prompt. usado como o prompt podem ser modificados atribuio a _PROMPT.
O par de aspas mais externo para o interpretador de comandos e o par mais interno para Lua. O uso de -i para entrar em modo interativo; caso contrrio, o programa iria terminar silenciosamente logo aps a atribuio a _PROMPT. Para permitir o uso de Lua como um interpretador de scripts em sistemas Unix, o interpretador de linha de comando pula a primeira linha de um trecho de cdigo se ele comea com #. Portanto, scripts Lua podem ser usados como programas executveis usando chmod +x e a forma #!, como em
#!/usr/local/bin/lua
claro que a localizao do interpretador Lua pode ser diferente na sua mquina. Se lua est em seu PATH, ento
#!/usr/bin/env lua
283
houve uma mudana sutil no escopo das variveis implcitas do comando for e do comando repeat; a sintaxe de cadeia longa/comentrio longo ([[string]]) no permite aninhamento. Pode-se usar a nova sintaxe ([=[string]=]) nesses casos (ver a opo de tempo de compilao LUA_COMPAT_LSTR em luaconf.h.)
284
stat ::=
varlist1 `= explist1 | | | |
if exp then block {elseif exp then block}[else block] end | for Name `= exp `, exp [`, exp] do block end for namelist in explist1 do block end function funcname funcbody local function Name funcbody local namelist [`= explist1] | | | |
break
var ::=
Name
prefixexp `[ exp `]
prefixexp `. Name
| |
false
true |
Number
String |
`...
prefixexp exp |
tableconstructor
exp binop |
unop exp
functioncall
`( exp `)
285
functioncall ::=
prefixexp args
args ::=
`( [explist1] `)
tableconstructor
String
`...
fieldlist ::= field {fieldsep field} [fieldsep] field ::= `[ exp `] `= exp | Name `= exp | exp
fieldsep ::= `,
`;
`- | |
`* |
`/ |
`^ `==
| |
`% `~=
| |
`..
`<= or | not
`> `#
`>=
unop ::= `-
286
Esta base de conectores pode ser importada por qualquer documento NCL 3.0.
<!-This is NCL Copyright: 2000-2005 PUC-RIO/LABORATORIO TELEMIDIA, All Rights Reserved. See http://www.telemidia.puc-rio.br Public URI: http://www.ncl.org.br/NCL3.0/connectorBases/causalConnBase.ncl Author: TeleMidia Laboratory Revision: 19/09/2006 --> <?xml version="1.0" encoding="ISO-8859-1"?> <ncl id="causalConnBase" xmlns="http://www.ncl.org.br/NCL3.0/CausalConnectorProfile"> <head> <connectorBase> <!-- OnBegin --> <causalConnector id="onBeginStart"> <simpleCondition role="onBegin"/> <simpleAction role="start"/> </causalConnector> <causalConnector id="onBeginStop"> <simpleCondition role="onBegin"/> <simpleAction role="stop"/> </causalConnector> <causalConnector id="onBeginPause"> <simpleCondition role="onBegin"/> <simpleAction role="pause"/> </causalConnector> <causalConnector id="onBeginResume"> <simpleCondition role="onBegin"/> <simpleAction role="resume"/> </causalConnector> <causalConnector id="onBeginSet"> <connectorParam name="var"/> <simpleCondition role="onBegin"/> <simpleAction role="set" value="$var"/> </causalConnector> <!-- OnEnd --> <causalConnector id="onEndStart"> <simpleCondition role="onEnd"/>
287
<simpleAction role="start"/> </causalConnector> <causalConnector id="onEndStop"> <simpleCondition role="onEnd"/> <simpleAction role="stop"/> </causalConnector> <causalConnector id="onEndPause"> <simpleCondition role="onEnd"/> <simpleAction role="pause"/> </causalConnector> <causalConnector id="onEndResume"> <simpleCondition role="onEnd"/> <simpleAction role="resume"/> </causalConnector> <causalConnector id="onEndSet"> <connectorParam name="var"/> <simpleCondition role="onEnd"/> <simpleAction role="set" value="$var"/> </causalConnector> <!-- OnMouseSelection --> <causalConnector id="onSelectionStart"> <simpleCondition role="onSelection"/> <simpleAction role="start" /> </causalConnector> <causalConnector id="onSelectionStop"> <simpleCondition role="onSelection"/> <simpleAction role="stop" /> </causalConnector> <causalConnector id="onSelectionPause"> <simpleCondition role="onSelection"/> <simpleAction role="pause" /> </causalConnector> <causalConnector id="onSelectionResume"> <simpleCondition role="onSelection"/> <simpleAction role="resume" /> </causalConnector> <causalConnector id="onSelectionSetVar"> <connectorParam name="var" /> <simpleCondition role="onSelection"/> <simpleAction role="set" value="$var"/> </causalConnector> <!-- OnKeySelection --> <causalConnector id="onKeySelectionStart"> <connectorParam name="keyCode"/> <simpleCondition role="onSelection" key="$keyCode"/> <simpleAction role="start"/> </causalConnector> <causalConnector id="onKeySelectionStop"> <connectorParam name="keyCode"/> <simpleCondition role="onSelection" key="$keyCode"/> <simpleAction role="stop"/>
288
</causalConnector> <causalConnector id="onKeySelectionPause"> <connectorParam name="keyCode"/> <simpleCondition role="onSelection" key="$keyCode"/> <simpleAction role="pause"/> </causalConnector> <causalConnector id="onKeySelectionResume"> <connectorParam name="keyCode"/> <simpleCondition role="onSelection" key="$keyCode"/> <simpleAction role="resume"/> </causalConnector> <causalConnector id="onKeySelectionSetVar"> <connectorParam name="keyCode"/> <connectorParam name="var"/> <simpleCondition role="onSelection" key="$keyCode"/> <simpleAction role="set" value="$var"/> </causalConnector> <!-- OnBeginAttribution --> <causalConnector id="onBeginAttributionStart"> <simpleCondition role="onBeginAttribution"/> <simpleAction role="start"/> </causalConnector> <causalConnector id="onBeginAttributionStop"> <simpleCondition role="onBeginAttribution"/> <simpleAction role="stop"/> </causalConnector> <causalConnector id="onBeginAttributionPause"> <simpleCondition role="onBeginAttribution"/> <simpleAction role="pause"/> </causalConnector> <causalConnector id="onBeginAttributionResume"> <simpleCondition role="onBeginAttribution"/> <simpleAction role="resume"/> </causalConnector> <causalConnector id="onBeginAttributionSet"> <connectorParam name="var"/> <simpleCondition role="onBeginAttribution"/> <simpleAction role="set" value="$var"/> </causalConnector> <!-- OnEndAttribution --> <causalConnector id="onEndAttributionStart"> <simpleCondition role="onEndAttribution"/> <simpleAction role="start"/> </causalConnector> <causalConnector id="onEndAttributionStop"> <simpleCondition role="onEndAttribution"/> <simpleAction role="stop"/> </causalConnector> <causalConnector id="onEndAttributionPause"> <simpleCondition role="onEndAttribution"/> <simpleAction role="pause"/> </causalConnector>
289
<causalConnector id="onEndAttributionResume"> <simpleCondition role="onEndAttribution"/> <simpleAction role="resume"/> </causalConnector> <causalConnector id="onEndAttributionSet"> <connectorParam name="var"/> <simpleCondition role="onEnd"/> <simpleAction role="set" value="$var"/> </causalConnector> <!-- OnBegin multiple actions --> <causalConnector id="onBeginStartStop"> <simpleCondition role="onBegin"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="stop"/> </compoundAction> </causalConnector> <causalConnector id="onBeginStartPause"> <simpleCondition role="onBegin"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="pause"/> </compoundAction> </causalConnector> <causalConnector id="onBeginStartResume"> <simpleCondition role="onBegin"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="resume"/> </compoundAction> </causalConnector> <causalConnector id="onBeginStartSet"> <connectorParam name="var"/> <simpleCondition role="onBegin"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="set" value="$var"/> </compoundAction> </causalConnector> <causalConnector id="onBeginStopStart"> <simpleCondition role="onBegin"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="start"/> </compoundAction> </causalConnector> <causalConnector id="onBeginStopPause"> <simpleCondition role="onBegin"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="pause"/> </compoundAction> </causalConnector>
290
<causalConnector id="onBeginStopResume"> <simpleCondition role="onBegin"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="resume"/> </compoundAction> </causalConnector> <causalConnector id="onBeginStopSet"> <connectorParam name="var"/> <simpleCondition role="onBegin"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="set" value="$var"/> </compoundAction> </causalConnector> <causalConnector id="onBeginSetStart"> <connectorParam name="var"/> <simpleCondition role="onBegin"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="start"/> </compoundAction> </causalConnector> <causalConnector id="onBeginSetStop"> <connectorParam name="var"/> <simpleCondition role="onBegin"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="stop"/> </compoundAction> </causalConnector> <causalConnector id="onBeginSetPause"> <connectorParam name="var"/> <simpleCondition role="onBegin"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="pause"/> </compoundAction> </causalConnector> <causalConnector id="onBeginSetResume"> <connectorParam name="var"/> <simpleCondition role="onBegin"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="resume"/> </compoundAction> </causalConnector> <!-- OnEnd multiple actions --> <causalConnector id="onEndStartStop"> <simpleCondition role="onEnd"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="stop"/> </compoundAction> </causalConnector>
291
<causalConnector id="onEndStartPause"> <simpleCondition role="onEnd"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="pause"/> </compoundAction> </causalConnector> <causalConnector id="onEndStartResume"> <simpleCondition role="onEnd"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="resume"/> </compoundAction> </causalConnector> <causalConnector id="onEndStartSet"> <connectorParam name="var"/> <simpleCondition role="onEnd"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="set" value="$var"/> </compoundAction> </causalConnector> <causalConnector id="onEndStopStart"> <simpleCondition role="onEnd"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="start"/> </compoundAction> </causalConnector> <causalConnector id="onEndStopPause"> <simpleCondition role="onEnd"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="pause"/> </compoundAction> </causalConnector> <causalConnector id="onEndStopResume"> <simpleCondition role="onEnd"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="resume"/> </compoundAction> </causalConnector> <causalConnector id="onEndStopSet"> <connectorParam name="var"/> <simpleCondition role="onEnd"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="set" value="$var"/> </compoundAction> </causalConnector> <causalConnector id="onEndSetStart"> <connectorParam name="var"/> <simpleCondition role="onEnd"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="start"/> </compoundAction>
292
</causalConnector> <causalConnector id="onEndSetStop"> <connectorParam name="var"/> <simpleCondition role="onEnd"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="stop"/> </compoundAction> </causalConnector> <causalConnector id="onEndSetPause"> <connectorParam name="var"/> <simpleCondition role="onEnd"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="pause"/> </compoundAction> </causalConnector> <causalConnector id="onEndSetResume"> <connectorParam name="var"/> <simpleCondition role="onEnd"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="resume"/> </compoundAction> </causalConnector> <!-- OnMouseSelection multiple actions --> <causalConnector id="onSelectionStartStop"> <simpleCondition role="onSelection"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="stop"/> </compoundAction> </causalConnector> <causalConnector id="onSelectionStartPause"> <simpleCondition role="onSelection"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="pause"/> </compoundAction> </causalConnector> <causalConnector id="onSelectionStartResume"> <simpleCondition role="onSelection"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="resume"/> </compoundAction> </causalConnector> <causalConnector id="onSelectionStartSet"> <connectorParam name="var"/> <simpleCondition role="onSelection"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="set" value="$var"/> </compoundAction> </causalConnector>
293
<causalConnector id="onSelectionStopStart"> <simpleCondition role="onEnd"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="start"/> </compoundAction> </causalConnector> <causalConnector id="onSelectionStopPause"> <simpleCondition role="onSelection"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="pause"/> </compoundAction> </causalConnector> <causalConnector id="onSelectionStopResume"> <simpleCondition role="onSelection"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="resume"/> </compoundAction> </causalConnector> <causalConnector id="onSelectionStopSet"> <connectorParam name="var"/> <simpleCondition role="onSelection"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="set" value="$var"/> </compoundAction> </causalConnector> <causalConnector id="onSelectionSetStart"> <connectorParam name="var"/> <simpleCondition role="onSelection"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="start"/> </compoundAction> </causalConnector> <causalConnector id="onSelectionSetStop"> <connectorParam name="var"/> <simpleCondition role="onSelection"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="stop"/> </compoundAction> </causalConnector> <causalConnector id="onSelectionSetPause"> <connectorParam name="var"/> <simpleCondition role="onSelection"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="pause"/> </compoundAction> </causalConnector> <causalConnector id="onSelectionSetResume"> <connectorParam name="var"/> <simpleCondition role="onSelection"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/>
294
<simpleAction role="resume"/> </compoundAction> </causalConnector> <!-- OnKeySelection multiple actions --> <causalConnector id="onKeySelectionStartStop"> <connectorParam name="keyCode"/> <simpleCondition role="onSelection" key="$keyCode"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="stop"/> </compoundAction> </causalConnector> <causalConnector id="onKeySelectionStartPause"> <connectorParam name="keyCode"/> <simpleCondition role="onSelection" key="$keyCode"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="pause"/> </compoundAction> </causalConnector> <causalConnector id="onKeySelectionStartResume"> <connectorParam name="keyCode"/> <simpleCondition role="onSelection" key="$keyCode"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="resume"/> </compoundAction> </causalConnector> <causalConnector id="onKeySelectionStartSet"> <connectorParam name="var"/> <connectorParam name="keyCode"/> <simpleCondition role="onSelection" key="$keyCode"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="set" value="$var"/> </compoundAction> </causalConnector> <causalConnector id="onKeySelectionStopStart"> <connectorParam name="keyCode"/> <simpleCondition role="onSelection" key="$keyCode"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="start"/> </compoundAction> </causalConnector> <causalConnector id="onKeySelectionStopPause"> <connectorParam name="keyCode"/> <simpleCondition role="onSelection" key="$keyCode"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="pause"/> </compoundAction> </causalConnector>
295
<causalConnector id="onKeySelectionStopResume"> <connectorParam name="keyCode"/> <simpleCondition role="onSelection" key="$keyCode"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="resume"/> </compoundAction> </causalConnector> <causalConnector id="onKeySelectionStopSet"> <connectorParam name="var"/> <connectorParam name="keyCode"/> <simpleCondition role="onSelection" key="$keyCode"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="set" value="$var"/> </compoundAction> </causalConnector> <causalConnector id="onKeySelectionSetStart"> <connectorParam name="var"/> <connectorParam name="keyCode"/> <simpleCondition role="onSelection" key="$keyCode"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="start"/> </compoundAction> </causalConnector> <causalConnector id="onKeySelectionSetStop"> <connectorParam name="var"/> <connectorParam name="keyCode"/> <simpleCondition role="onSelection" key="$keyCode"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="stop"/> </compoundAction> </causalConnector> <causalConnector id="onKeySelectionSetPause"> <connectorParam name="var"/> <connectorParam name="keyCode"/> <simpleCondition role="onSelection" key="$keyCode"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="pause"/> </compoundAction> </causalConnector> <causalConnector id="onKeySelectionSetResume"> <connectorParam name="var"/> <connectorParam name="keyCode"/> <simpleCondition role="onSelection" key="$keyCode"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="resume"/> </compoundAction> </causalConnector> <!-- OnBeginAttribution multiple actions -->
296
<causalConnector id="onBeginAttributionStartStop"> <simpleCondition role="onBeginAttribution"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="stop"/> </compoundAction> </causalConnector> <causalConnector id="onBeginAttributionStartPause"> <simpleCondition role="onBeginAttribution"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="pause"/> </compoundAction> </causalConnector> <causalConnector id="onBeginAttributionStartResume"> <simpleCondition role="onBeginAttribution"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="resume"/> </compoundAction> </causalConnector> <causalConnector id="onBeginAttributionStartSet"> <connectorParam name="var"/> <simpleCondition role="onBeginAttribution"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="set" value="$var"/> </compoundAction> </causalConnector> <causalConnector id="onBeginAttributionStopStart"> <simpleCondition role="onBeginAttribution"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="start"/> </compoundAction> </causalConnector> <causalConnector id="onBeginAttributionStopPause"> <simpleCondition role="onBeginAttribution"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="pause"/> </compoundAction> </causalConnector> <causalConnector id="onBeginAttributionStopResume"> <simpleCondition role="onBeginAttribution"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="resume"/> </compoundAction> </causalConnector> <causalConnector id="onBeginAttributionStopSet"> <connectorParam name="var"/> <simpleCondition role="onBeginAttribution"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="set" value="$var"/> </compoundAction> </causalConnector>
297
<causalConnector id="onBeginAttributionSetStart"> <connectorParam name="var"/> <simpleCondition role="onBeginAttribution"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="start"/> </compoundAction> </causalConnector> <causalConnector id="onBeginAttributionSetStop"> <connectorParam name="var"/> <simpleCondition role="onBeginAttribution"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="stop"/> </compoundAction> </causalConnector> <causalConnector id="onBeginAttributionSetPause"> <connectorParam name="var"/> <simpleCondition role="onBeginAttribution"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="pause"/> </compoundAction> </causalConnector> <causalConnector id="onBeginAttributionSetResume"> <connectorParam name="var"/> <simpleCondition role="onBeginAttribution"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="resume"/> </compoundAction> </causalConnector> <!-- OnEndAttribution multiple actions --> <causalConnector id="onEndAttributionStartStop"> <simpleCondition role="onEndAttribution"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="stop"/> </compoundAction> </causalConnector> <causalConnector id="onEndAttributionStartPause"> <simpleCondition role="onEndAttribution"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="pause"/> </compoundAction> </causalConnector> <causalConnector id="onEndAttributionStartResume"> <simpleCondition role="onEndAttribution"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="resume"/> </compoundAction> </causalConnector>
298
<causalConnector id="onEndAttributionStartSet"> <connectorParam name="var"/> <simpleCondition role="onEndAttribution"/> <compoundAction operator="seq"> <simpleAction role="start"/> <simpleAction role="set" value="$var"/> </compoundAction> </causalConnector> <causalConnector id="onEndAttributionStopStart"> <simpleCondition role="onEndAttribution"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="start"/> </compoundAction> </causalConnector> <causalConnector id="onEndAttributionStopPause"> <simpleCondition role="onEndAttribution"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="pause"/> </compoundAction> </causalConnector> <causalConnector id="onEndAttributionStopResume"> <simpleCondition role="onEndAttribution"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="resume"/> </compoundAction> </causalConnector> <causalConnector id="onEndAttributionStopSet"> <connectorParam name="var"/> <simpleCondition role="onEndAttribution"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="set" value="$var"/> </compoundAction> </causalConnector> <causalConnector id="onEndAttributionSetStart"> <connectorParam name="var"/> <simpleCondition role="onEndAttribution"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="start"/> </compoundAction> </causalConnector> <causalConnector id="onEndAttributionSetStop"> <connectorParam name="var"/> <simpleCondition role="onEndAttribution"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="stop"/> </compoundAction> </causalConnector> <causalConnector id="onEndAttributionSetPause"> <connectorParam name="var"/> <simpleCondition role="onEndAttribution"/> <simpleAction role="set" value="$var"/>
299
<simpleAction role="pause"/> </compoundAction> </causalConnector> <causalConnector id="onEndAttributionSetResume"> <connectorParam name="var"/> <simpleCondition role="onEndAttribution"/> <compoundAction operator="seq"> <simpleAction role="set" value="$var"/> <simpleAction role="resume"/> </compoundAction> </causalConnector> <!--Miscellaneous--> <causalConnector id="onKeySelectionStopResizePauseStart"> <connectorParam name="width"/> <connectorParam name="height"/> <connectorParam name="left"/> <connectorParam name="top"/> <connectorParam name="keyCode"/> <simpleCondition role="onSelection" key="$keyCode"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="setWidth" value="$width"/> <simpleAction role="setHeight" value="$height"/> <simpleAction role="setLeft" value="$left"/> <simpleAction role="setTop" value="$top"/> <simpleAction role="pause"/> <simpleAction role="start"/> </compoundAction> </causalConnector> <causalConnector id="onEndResizeResume"> <connectorParam name="left"/> <connectorParam name="top"/> <connectorParam name="width"/> <connectorParam name="height"/> <simpleCondition role="onEnd"/> <compoundAction operator="seq"> <simpleAction role="setLeft" value="$left"/> <simpleAction role="setTop" value="$top"/> <simpleAction role="setWidth" value="$width"/> <simpleAction role="setHeight" value="$height"/> <simpleAction role="resume"/> </compoundAction> </causalConnector> <causalConnector id="onKeySelectionStopSetPauseStart"> <connectorParam name="bounds"/> <connectorParam name="keyCode"/> <simpleCondition role="onSelection" key="$keyCode"/> <compoundAction operator="seq"> <simpleAction role="stop"/> <simpleAction role="set" value="$bounds"/> <simpleAction role="pause"/> <simpleAction role="start"/> </compoundAction> </causalConnector> </connectorBase> </head> </ncl>
300
Bibliografia
ITU Recommendation J.201:2004, Harmonization of declarative content format for interactive television applications ARIB STD-B24:2004, Data coding and transmission specifications for digital broadcasting Cascading Style Sheets, Cascading Style Sheets, level 2, Bert Bos, Hkon Wium Lie, Chris Lilley, Ian Jacobs. W3C Recommendation 12. Maio de 1998, disponnel em <http://www.w3.org/TR/REC-CSS2> DVB-HTML, Perrot P. DVB-HTML - An Optional Declarative Language within MHP 1.1, EBU Technical Review. 2001 Namespaces in XML, Namespaces in XML, W3C Recommendation. Janeiro de 1999 NCM Core, Soares L.F.G; Rodrigues R.F. Nested Context Model 3.0: Part 1 NCM Core, Technical Report, Departamento de Informtica PUC-Rio. Maio de 2005, ISSN: 0103-9741. Tambm disponvel em <http://www.ncl.org.br> NCL Digital TV Profiles, Soares L.F.G; Rodrigues R.F. Part 8 NCL (Nested Context Language) Digital TV Profiles, Technical Report, Departamento de Informtica PUC-Rio, No. 35/06. Outubro de 2006, ISSN: 0103-9741. Tambm disponvel em <http://www.ncl.org.br> NCL Live Editing Commands, Soares L.F.G; Rodrigues R.F; Costa, R.R.; Moreno, M.F. Part 9 NCL Live Editing Commands. Technical Report, Departamento de Informtica PUC-Rio, No. 36/06. Dezembro de 2006, ISSN: 0103-9741. Tambm disponvel em <http://www.ncl.org.br> NCL-Lua, Cerqueira, R,; SantAnna, F. Nested Context Model 3.0: Part 11 Lua Scripting Language for NCL, Technical Report, Departamento de Informtica PUC-Rio. Maio de 2007, ISSN: 0103-9741. NCL Main Profile, Soares L.F.G; Rodrigues R.F; Costa, R.R. Nested Context Model 3.0: Part 6 NCL (Nested Context Language) Main Profile, Technical Report, Departamento de Informtica PUC-Rio. Maio de 2005, ISSN: 0103-9741. Tambm disponvel em <http://www.ncl.org.br> RDF, Resource Description Framework (RDF) Model and Syntax Specification, Ora Lassila and Ralph R. Swick. W3C Recommendation. 22 de fevereiro de 1999. Disponvel em <http://www.w3.org/TR/REC-rdfsyntax/> SMIL 2.1 Specification, SMIL 2.1 - Synchronized Multimedia Integration Language SMIL 2.1 Specification, W3C Recommendation. Dezembro de 2005 XHTML 1.0, XHTML 1.0 2 Edition - Extensible HyperText Markup Language, W3C Recommendation, Agosto de 2002 Programming in Lua, ISBN 85-903798-2-5. Segunda Edio, de Roberto Ierusalimschy et al. Maro de 2006,
[7]
[8]
[9] [10]
[11]
ACAP, Advanced Application Platform (ACAP), ATSC Standard: Document A/101. Agosto de 2005
301