Criando extensões de C Python usando o Carbide.c++

From Forum Nokia Wiki

Introdução

Esse tutorial explica como fazer extensões de PyS60 usando o Carbide.c++.

Precondições

Primeiro, instale o Nokia S60 Platform SDKs para Symbian OS, o qual pode ser encontrado aqui. (Nesse tutorial nós usaremos a versão S60 3rd Edition, FP2 v1.1 do SDK). Esses SDKs contêm alguns arquivos necessários para compilar a extensão. Porém, eles não contêm os arquivos de Python, tais como python.h e python222.lib. Para adicionar esses arquivos importantes, instale a versão para SDK do Python para s60. Primeiro, faça o download do arquivo PythonForS60_X_X_X_SDK_3rdEd.zip, o qual pode ser encontrado aqui, em que X é a versão do pacote (nesse tutorial nós usamos PyS60 v1.4.5). Em seguida, descompacte o conteúdo do arquivo zip interno (sdk_files.zip) dentro do diretório do SDK (nesse caso, C:\S60\devices\S60_3rd_FP2_SDK_v1.1). Essa operação irá adicionar os arquivos de Python ao diretório C:\S60\devices\S60_3rd_FP2_SDK_v1.1\epoc32.

Depois de instalar o SDK e os arquivos de Python, instale o Carbide.c++, que é um excelente ambiente integrado de desenvolvimento (IDE) para criar software C/C++ para a plataforma s60. O arquivo de instalação do Carbide.C++ pode ser encontrado aqui.

Importando o exemplo

Agora, faça o dowload do pacote do exemplo aqui e descompacte em um diretório qualquer (nete que o diretório não pode conter espaços no nome como c:\nova pasta).

Abra o Carbide.c++, e vá ao menu File->Import. Escolha Symbian OS->Symbian OS Bld.inf file e aperte o botão Next.

Procure o arquivo bld.inf, o qual está localizado no diretório group do exemplo descompactado. Aperte o botão Next.

Escolha Phone Release (GCCE) e aperte os botões Next e Finish em sequência.

Agora já é possível ver os arquivos do exemplo no Carbide.c++.

Este é um exemplo bastante simples que mostra um information note vazio.

Analizando o exemplo

Os arquivos mais importantes para serem analizados são none.h e none.cpp.

No arquivo none.h nós incluímos alguns arquivos de cabeçalho importantes.

e32base.h: para CBase;

e32std.h: para descritores;

aknnotewrappers.h: para os information notes ;

Python.h: para coisas de Python;

symbian_python_ext_util.h: Para tratamento de erro.

#ifndef __NONE_H__
#define __NONE_H__
 
//  Include Files
 
#include 	// CBase
#include 	 // TBuf
#include
#include "Python.h"
#include "symbian_python_ext_util.h"
 
//  Class Definitions
 
class Cnone : public CBase
	{
public:
	// new functions
	IMPORT_C static Cnone* NewL();
	IMPORT_C static Cnone* NewLC();
	IMPORT_C ~Cnone();
 
public: // new functions, example API
	IMPORT_C void ShowConfirmationNote();
 
private: // new functions
	Cnone();
	void ConstructL();
 
private: // data
	};
 
#endif  // __NONE_H__

Outros itens nesse arquivo são os construtores e definições de métodos, tais como o método ShowConfirmationNote().

No arquivo none.cpp pode-se ver a sentença include de none.h. Seguindo o exemplo, pode-se ver o método ShowConfirmationNote(), o qual apenas chama o método ExecuteLD() de um objeto CAknInformationNote. Essa função faz o que nós queremos (a exibição de um information note vazio), mas essa função não pode ser chamada diretamente a partir do Python. Assim, temos que criar uma função que possa ser chamada a partir do Python. Essa função recebe parâmetros de Python, converte esses parâmetros para a linguagem C, chama métodos de C++ para Symbian e retorna um objeto Python para o chamador da função.

#include "none.h"	// Cnone
#include "none.pan"	  	// panic codes
 
//  Member Functions
 
EXPORT_C Cnone* Cnone::NewLC()
	{
	Cnone* self = new (ELeave) Cnone;
	CleanupStack::PushL(self);
	self-&gt;ConstructL();
	return self;
	}
 
EXPORT_C Cnone* Cnone::NewL()
	{
	Cnone* self = Cnone::NewLC();
	CleanupStack::Pop(self);
	return self;
	}
 
Cnone::Cnone()
// note, CBase initialises all member variables to zero
	{
	}
 
void Cnone::ConstructL()
	{
	}
 
EXPORT_C Cnone::~Cnone()
	{
	}
 
EXPORT_C void Cnone::ShowConfirmationNote()
	{
	CAknInformationNote* dialog = new(ELeave)CAknInformationNote();
	dialog-&gt;ExecuteLD();
	}
 
static PyObject* show_note(PyObject* /*self*/, PyObject* args)
	{
 
	TInt error;
	Cnone* obj = Cnone::NewL();
	TRAP(error, obj-&gt;ShowConfirmationNote());
	if (error)
		return SPyErr_SetFromSymbianOSErr(error);
	delete obj;
	Py_INCREF(Py_None);
	return Py_None;
	}
 
static const PyMethodDef none_methods[] =
	{
		{
		"show_note", (PyCFunction)show_note, METH_VARARGS, "shows a note."
		},
		{
		0, 0
		}
	};
 
DL_EXPORT(void) init_none()
	{
	Py_InitModule("none", (PyMethodDef*) none_methods);
	}

A função show_note recebe dois parâmetros do tipo PyObject. O primeiro parâmetro é o self e o segundo parâmetro é uma tupla contendo argumentos. No corpo da função o método ShowConfirmationNote é chamado em um TRAP. O TRAP coloca um código de erro diferente de zero em um inteiro se um erro ocorrer. A sentença SPyErr_SetFromSymbianOSErr(error) é chamada se um erro ocorrer. Ela apenas converte os erros de Symbian OS para erros de Python. Se nenhum erro ocorrer, o note será exibido e a função retornará um Py_None.

Em seguida, nós temos um PyMethodDef, o qual é uma tabela contendo os nomes das funções de Python e as funções de C que serão associadas a esses nomes. Essa tabela também contém uma flag que diz ao interpretador a convenção a ser usada para a chamada da função em C. Normalmente é sempre "METH_VARARGS" ou "METH_VARARGS | METH_KEYWORDS". Se for desejável adicionar mais funções, essas funções devem ser adicionadas nessa tabela.

A próxima função é a init_none(). Essa função passa a tabela de métodos para o interpretador na função de inicialização do módulo. A função de inicialização deve ser nomeada initname(), onde name é o nome do módulo e deve ser o único ítem non-static definido no arquivo odo módulo. A função Py_InitModule é chamada, a qual recebe o nome do módulo e a tabela de métodos.

Construíndo o exemplo

Primeiramente, usando o Carbide.c++, vá no diretório group e abra o arquivo none.mmp. Na tab Overview nós temos o Target name (none.pyd), Target type (DLL) e UID2 (deve ser 0x1000008d)

Abra a tab Libraries e adicione as bibliotecas euser.lib, python222.lib, avkon.lib, eikcdlg.lib e eikctl.lib

Abra a tab Options e adicione esses caminhos para o System includes (em Compiler Settings): \epoc32\include, \epoc32\include\libc and \epoc32\include\python. Também adicione essas capabilities: LocalServices, NetworkServices, ReadUserData, UserEnvironment e WriteUserData.

Vá ao menu Project->Properties. Expanda as opções do Carbide.c++ e selecione Build Configurations.

Na tab SIS Builder, aperte o botão Add e procure pelo arquivo ".pkg" (o qual está no diretório sis). Escolha o nome do arquivo de saída e selecione Don't sign sis file. Aperte o botão OK.

Vá ao menu Project->Freeze Exports. Finalmete, vá ao menu Project->Build Project.

Pós-Condições

Se tudo ocorrer sem problemas, o arquivo sis será criado dentro do diretório sis do projeto.

Community: Wiki