🛡️ SafeWrap - Wrapper Seguro para Funções SA-MP

O SafeWrap é uma biblioteca completa para SA-MP (San Andreas Multiplayer) que fornece wrappers seguros em torno das funções nativas para prevenir erros comuns e melhorar a estabilidade do servidor. Desenvolvido por Jhon & Kaique, esta biblioteca oferece tratamento de erros avançado, validação de parâmetros e capacidades de depuração.

✨ Características Principais

· Sistema de Tratamento de Erros: Sistema completo de enumeração e rastreamento de erros · Validação de Parâmetros: Verificação automática de valores nulos e intervalos · Operações Seguras com Strings: Manipulação protegida de strings com prevenção de overflow · Verificações de Segurança: Validação de jogadores antes de operações · Ferramentas de Depuração: Sistema de logging e assertions integrado · Proteção de Memória: Operações de arquivo e acesso à memória protegidos · Compatibilidade: Wrappers compatíveis com ALS que não quebram código existente

#include <a_safewrap>

🚀 Começo Rápido

Uso Básico

public OnGameModeInit() {
    Safewrap_Init(); // Inicializa o sistema SafeWrap
    
    // Use os wrappers seguros instead das funções nativas
    SW_SendClientMessageToAll(0xFFFFFFFF, "Servidor iniciado com protecak SafeWrap!");
    return 1;
}

Exemplo de Tratamento de Erros

public OnPlayerConnect(playerid) {
    new nomeJogador[MAX_PLAYER_NAME];
    
    // Recuperação segura do nome do jogador
    if(!SW_GetPlayerName(playerid, nomeJogador)) {
        new erro = Safewrap_GetLastError();
        printf("Falha ao pegar nome do jogador: Erro %d", erro);
        return 0;
    }
    
    printf("%s entrou no servidor", SW_PlayerName(playerid));
    return 1;
}

Operações Seguras com Strings

stock MensagemBoasVindasSegura(playerid, const nome[]) {
    SW_NullCheck(nome); // Verificação automática de valor nulo
    
    new mensagem[128];
    SW_format(mensagem, sizeof(mensagem), "Bem-vindo, %s! Aproveite sua estadia.", nome);
    
    if(Safewrap_GetLastError() == SAFEWRAP_ERROR_STRING_OVERFLOW) {
        SW_SendClientMessage(playerid, 0xFF0000FF, "Bem-vindo! O nome era muito longo para exibir completamente.");
    } else {
        SW_SendClientMessage(playerid, 0x00FF00FF, mensagem);
    }
}

🔧 Configuração

Você pode personalizar o comportamento do SafeWrap com estas definições:

#define SAFEWRAP_MAX_STRING 1024    // Tamanho máximo personalizado para strings
#define SAFEWRAP_MAX_PLAYER_NAME 32 // Tamanho personalizado para nomes de jogador
#define SAFEWRAP_DEBUG true         // Ativa modo debug

📋 Referência da API

Funções Principais

· Safewrap_Init() - Inicializa o sistema SafeWrap · Safewrap_GetLastError() - Obtém o último código de erro · Safewrap_SetError(erro, dados_adicionais) - Define um erro manualmente · Safewrap_LogMessage(mensagem[], arquivo[] = "", linha = -1) - Registra uma mensagem de log

Macros Úteis

· SW_String(texto) - Representação segura de strings · SW_PlayerName(playerid) - Obtenção segura de nome de jogador · SW_Log(mensagem) - Log com informações de arquivo e linha · SW_Assert(condição, mensagem) - Verificação de assertions em tempo de execução · SW_Try(operação) - Bloco de operação com tratamento de erro · SW_NullCheck(parâmetro) - Validação de parâmetros nulos · SW_RangeCheck(valor, mínimo, máximo) - Validação de intervalos

Funções Protegidas

O SafeWrap fornece versões seguras das funções comuns do SA-MP:

· SW_SetPlayerName, SW_GetPlayerName · SW_SendClientMessage, SW_SendClientMessageToAll · SW_CreateVehicle, SW_GetVehiclePos · SW_strcpy, SW_format · SW_fopen, SW_fread · SW_CallLocalFunction · SW_SetTimer

🛡️ Códigos de Erro

A biblioteca define estes tipos de erro em E_SAFEWRAP_ERROR:

· SAFEWRAP_ERROR_NONE - Nenhum erro · SAFEWRAP_ERROR_INVALID_PLAYER - ID de jogador inválido · SAFEWRAP_ERROR_INVALID_VEHICLE - ID de veículo inválido · SAFEWRAP_ERROR_STRING_OVERFLOW - Estouro de buffer de string · SAFEWRAP_ERROR_NULL_PARAM - Parâmetro nulo fornecido · SAFEWRAP_ERROR_RANGE - Valor fora do intervalo válido · E muito mais...

🔍 Depuração

Ative o modo debug para logs detalhados:

#define SAFEWRAP_DEBUG true

Use assertions para detectar problemas cedo:

SW_Assert(IsPlayerConnected(playerid), "Jogador deve estar conectado");

📝 Exemplos Práticos

Gerenciamento Seguro de Jogadores

stock KickarComRazaoSegura(playerid, const motivo[]) {
    SW_NullCheck(motivo);
    
    if(!IsPlayerConnected(playerid)) {
        return Safewrap_SetError(SAFEWRAP_ERROR_INVALID_PLAYER, playerid);
    }
    
    SW_SendClientMessage(playerid, 0xFF0000FF, motivo);
    return Safewrap_KickPlayerSafe(playerid, motivo);
}

Operações Protegidas com Arquivos

stock CarregarArquivoConfig(const nomearquivo[]) {
    new File:handle = SW_fopen(nomearquivo, "r");
    if(!handle) {
        SW_Log("Falha ao abrir arquivo de configuracao");
        return 0;
    }
    
    new linha[256];
    while(SW_fread(handle, linha)) {
        if(Safewrap_IsValidString(linha)) {
            ProcessarLinhaConfig(linha);
        }
    }
    
    fclose(handle);
    return 1;
}

🤝 Contribuindo

Aceitamos contribuições! Sinta-se à vontade para enviar pull requests ou abrir issues para bugs e solicitações de recursos.

📄 Licença

Copyright (c) 2025 Jhon & Kaique. Todos os direitos reservados.