# ohos_ksoap2

**Repository Path**: cbbgs/ohos_ksoap2

## Basic Information

- **Project Name**: ohos_ksoap2
- **Description**: ohos_ksoap2
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-14
- **Last Updated**: 2026-01-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# kSoap2

[![HarmonyOS](https://img.shields.io/badge/HarmonyOS-NEXT-blue)](https://developer.harmonyos.com)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-ArkTS-blue.svg)](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/arkts-get-started-0000001504769321-V3)

## 简介

kSoap2 鸿蒙化版本是基于知名的 kSoap2 库为华为 HarmonyOS NEXT 系统专门改造的 SOAP 客户端库。本项目使用 ArkTS 语言重新实现了完整的 SOAP 协议支持，为鸿蒙开发者提供了可靠、高效的 Web Services 访问能力。

### ✨ 主要特性

- 🔄 **完整的 SOAP 协议支持** - 支持 SOAP 1.1 和 SOAP 1.2 规范
- 🏗️ **动态对象构建** - 灵活的 SoapObject 动态对象构建机制
- 🔐 **多种认证方式** - 支持 Basic Auth、自定义认证等
- 📦 **自动序列化/反序列化** - 智能的对象序列化和反序列化处理
- 🧪 **类型安全** - 基于 ArkTS 的强类型支持
- 🛠️ **调试友好** - 内置调试工具和详细日志支持
- 📚 **丰富示例** - 提供完整的使用示例和最佳实践
- ⚡ **高性能** - 针对鸿蒙系统优化的网络传输层

## 下载安装
### 安装依赖

```
ohpm install @ohos/ksoap2
```

## 使用说明

### 基本使用

#### 1. 创建简单的 SOAP 请求

```typescript
import { 
  SoapObject, 
  SoapSerializationEnvelope, 
  HarmonyHttpTransport,
  SoapVersion 
} from '@ohos/ksoap2';

// 创建 SOAP 对象
const request = new SoapObject('http://tempuri.org/', 'GetWeather');
request.addProperty('cityName', '北京');
request.addProperty('countryName', '中国');

// 创建 SOAP 信封
const envelope = new SoapSerializationEnvelope(SoapVersion.VER11);
envelope.setOutputSoapObject(request);

// 创建传输层
const transport = new HarmonyHttpTransport('http://webservice.weather.com.cn/Weather.asmx');

try {
  // 发送请求
  await transport.call('http://tempuri.org/GetWeather', envelope);
  
  // 获取响应
  const result = envelope.getResponse();
  console.log('天气信息:', result);
} catch (error) {
  console.error('请求失败:', error);
}
```

#### 2. 使用认证

```typescript
import { HarmonyHttpTransportBasicAuth } from '@ohos/ksoap2';

// 创建带认证的传输层
const transport = new HarmonyHttpTransportBasicAuth(
  'http://tempuri.org/secure-service.asmx',
  'username',
  'password'
);

// 其余代码与基本使用相同
```

#### 3. 添加 SOAP Headers

```typescript
// 创建 Header 对象
const authHeader = new SoapObject('http://tempuri.org/', 'AuthHeader');
authHeader.addProperty('token', 'your-auth-token');
authHeader.addProperty('userId', 'user123');

// 添加到信封
envelope.headerOut = [authHeader];
```

### 错误处理

```typescript
try {
  await transport.call(soapAction, envelope);
  const response = envelope.getResponse();
} catch (error) {
  if (error instanceof SoapFault) {
    console.error('SOAP 故障:', error.getFaultString());
    console.error('故障代码:', error.getFaultCode());
  } else {
    console.error('网络错误:', error.message);
  }
}
```


## 接口说明

### SoapObject

动态 SOAP 对象，用于构建请求和解析响应。

| 方法 | 描述 |
|------|------|
| `constructor(namespace: string, name: string)` | 创建 SoapObject 实例 |
| `getName(): string` | 获取对象名称 |
| `getNamespace(): string` | 获取对象命名空间 |
| `getProperty(index: number): ESObject` | 按索引获取属性值 |
| `getPropertyByName(name: string): ESObject \| null` | 按名称获取属性值 |
| `getPropertyCount(): number` | 获取属性数量 |
| `addProperty(name: string, value: ESObject): void` | 添加属性 |
| `addPropertyWithInfo(propertyInfo: PropertyInfo, value: ESObject)` | 使用 PropertyInfo 添加属性 |
| `getAttributeInfoCompat(index: number, attributeInfo: AttributeInfo): void` | 获取兼容的属性信息 |
| `getAttributeInfo(index: number)` | 获取属性信息 |
| `getAttribute(name: string): ESObject` | 获取 XML 属性 |
| `getAttributeCount(): number` | 获取 XML 属性数量 |
| `addAttributeWithInfo(attributeInfo: AttributeInfo): void` | 使用 AttributeInfo 添加 XML 属性 |
| `getPropertyInfo(index: number, properties: Map<string, ESObject>, info: PropertyInfo): void` | 获取属性详细信息 |

### SoapSerializationEnvelope

SOAP 信封，负责序列化和反序列化。

| 方法 | 描述 |
|------|------|
| `constructor(version: SoapVersion)` | 创建序列化信封实例 |
| `parse(xmlContent: string): void` | 解析 XML 内容 |
| `write(): void` | 序列化为 XML |
| `setOutputSoapObject(request: SoapObject)` | 设置输出的 SOAP 对象 |
| `addMapping(namespace: string, name: string, clazz: string, marshal?: Marshal)` | 添加类型映射 |
| `getResponse()` | 获取响应对象 |
| `isAddAdornments()` | 检查是否添加装饰 |
| `setAddAdornments(addAdornments: boolean)` | 设置是否添加装饰 |

**属性:**

- `headerOut: ESObject[]` - 出站头部
- `headerIn: ESObject[]` - 入站头部

### SoapPrimitive

SOAP 基本类型包装器，用于处理简单数据类型。

| 方法 | 描述 |
|------|------|
| `constructor(namespace: string, name: string, value: ESObject)` | 创建 SoapPrimitive 实例 |
| `equals(other: ESObject)` | 比较两个对象是否相等 |
| `hashCode()` | 获取哈希码 |
| `getNamespace()` | 获取命名空间 |
| `getName()` | 获取名称 |

### PropertyInfo

属性信息描述，用于复杂类型映射和序列化配置。

| 方法 | 描述 |
|------|------|
| `constructor()` | 创建 PropertyInfo 实例 |
| `clear(): void` | 清空属性信息 |
| `getElementType(): PropertyInfo` | 获取元素类型 |
| `setElementType(elementType: PropertyInfo): void` | 设置元素类型 |
| `getName(): string` | 获取属性名称 |
| `setName(name: string): void` | 设置属性名称 |
| `getNamespace(): string` | 获取属性命名空间 |
| `setNamespace(namespace: string): void` | 设置属性命名空间 |
| `getType(): string` | 获取属性类型 |
| `setType(type: string): void` | 设置属性类型 |
| `getValue(): ESObject \| null` | 获取属性值 |
| `setValue(value: ESObject): void` | 设置属性值 |

### HttpTransportSE (HarmonyHttpTransport)

HTTP 传输层，负责网络通信。

| 方法 | 描述 |
|------|------|
| `constructor(url: string)` | 创建 HTTP 传输实例 |
| `call(soapAction: string, envelope: SoapEnvelope): Promise<void>` | 发送 SOAP 请求 |
| `setRequestMethod(methodType: 'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'HEAD' \| 'OPTIONS' \| 'PATCH')` | 设置请求方法 |

### HttpTransportBasicAuth (HarmonyHttpTransportBasicAuth)

支持 Basic 认证的 HTTP 传输层。

| 方法 | 描述 |
|------|------|
| `constructor(url: string, username?: string, password?: string)` | 创建支持 Basic 认证的传输实例 |
| `call(soapAction: string, envelope: SoapEnvelope): Promise<void>` | 发送带认证的 SOAP 请求 |
| `setRequestMethod(methodType: 'GET' \| 'POST' \| 'PUT' \| 'DELETE' \| 'HEAD' \| 'OPTIONS' \| 'PATCH')` | 设置请求方法 |

## 关于混淆

代码混淆，请查看代码混淆简介
如果希望materialprogressbar库在代码混淆过程中不会被混淆，需要在混淆规则配置文件obfuscation-rules.txt中添加相应的排除规则：
```
-keep
./oh_modules/@ohos/materialprogressbar
```

## 约束与限制
- **HarmonyOS NEXT** API 12 或更高版本
- **DevEco Studio** 5.0 或更高版本
- **ArkTS** 支持

## 目录结构

```
ksoap2_Harmony2/
├── library/                                    # 核心库代码
│   ├── src/main/ets/                           # 核心代码
│   │   ├── serialization/                      # 序列化模块
│   │   │   ├── SoapObject.ets                  # SOAP 对象
│   │   │   ├── SoapSerializationEnvelope.ets   # 序列化信封
│   │   │   ├── PropertyInfo.ets                # 属性信息
│   │   │   ├── SoapPrimitive.ets               # 基本类型包装
│   │   │   ├── AttributeInfo.ets               # 属性信息
│   │   │   ├── KvmSerializable.ets             # 可序列化接口
│   │   │   ├── Marshal.ets                     # 序列化接口
│   │   │   ├── DM.ets                          # 默认序列化器
│   │   │   ├── Marshal*.ets                    # 各种类型序列化器
│   │   │   └── index.ets                       # 导出文件
│   │   ├── transport/                          # 传输层模块
│   │   │   ├── HarmonyHttpTransport.ets        # HTTP 传输
│   │   │   ├── HarmonyServiceConnection.ets    # 服务连接
│   │   │   ├── ServiceConnection.ets           # 连接接口
│   │   │   ├── Transport.ets                   # 传输接口
│   │   │   ├── TransportFactory.ets            # 传输工厂
│   │   │   └── index.ets                       # 导出文件
│   │   ├── extras/                             # 扩展功能
│   │   │   └── HarmonyHttpTransportBasicAuth.ets # 基础认证
│   │   ├── type/                               # 类型定义
│   │   │   └── types.ets                       # 类型定义
│   │   ├── util/                               # 工具类
│   │   │   └── utils.ets                       # 工具函数
│   │   ├── SoapEnvelope.ets                    # SOAP 信封
│   │   └── SoapFault.ets                       # SOAP 错误
│   ├── Index.ets                               # 主导出文件
│   ├── build-profile.json5                     # 构建配置
│   └── oh-package.json5                        # 包配置
```

## 贡献代码

使用过程中发现任何问题都可以提 [Issue](https://gitcode.com/OpenHarmony-ApplicationTPC/ohos_ksoap2) 给组件，当然，也非常欢迎发 PR共建 。


## 开源协议

本项目采用 [MIT License](https://gitcode.com/OpenHarmony-ApplicationTPC/ohos_ksoap2) 开源协议。