ss7client

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 14, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

README

ss7-3eai-gateway-client

Go client and NATS wire contract for ss7-3eai-gateway, an SS7 signalling gateway (M3UA / SCCP / TCAP / MAP) that applications drive over NATS.

Licensed under the Apache License 2.0, separately from the gateway (AGPL-3.0-only), so an SMSC or any other application can link it under any licence.

go get github.com/3eAI-Labs/ss7-3eai-gateway-client

What it covers

The interfaces the gateway implements end to end — the MAP short-message path, subscriber location and state, and call routing:

Operation Method Subjects
SendRoutingInfoForSM (MAP op 45) SendRoutingInfoForSM map.sri.request → map.sri.response
MT-ForwardSM (MAP op 44) MTForwardSM map.mt.sms.request → map.mt.sms.response
MO-ForwardSM (MAP op 46), received from a foreign MSC SubscribeMO map.mo.sms
AnyTimeInterrogation (MAP op 71), towards the HLR AnyTimeInterrogation map.ati.request → map.ati.response
ProvideSubscriberInfo (MAP op 70), towards the VLR ProvideSubscriberInfo map.psi.request → map.psi.response
SendRoutingInfo (MAP op 22), towards the HLR, as GMSC — gateway 0.7.6 and later SendRoutingInfo map.routing.request → map.routing.response

The package also defines the Message JSON schema, parameter keys, status values and the gateway's failure codes — the contract for consumers in other languages.

Usage

nc, err := nats.Connect(natsURL)
if err != nil { /* ... */ }
defer nc.Close()

gw, err := ss7client.New(nc)
if err != nil { /* ... */ }
defer gw.Close()

sri, err := gw.SendRoutingInfoForSM(ctx, ss7client.SRIRequest{
	MSISDN:               "905321112233",
	ServiceCentreAddress: ss7client.E164("905001112233"),
})
if err != nil { /* *ss7client.GatewayError, ErrInvalidRequest, or a context error */ }

_, err = gw.MTForwardSM(ctx, ss7client.MTRequest{
	IMSI:                 sri.IMSI,
	NetworkNodeNumber:    ss7client.E164(sri.NetworkNodeNumber),
	ServiceCentreAddress: ss7client.E164("905001112233"),
	TPDU:                 smsDeliverTPDU, // 3GPP TS 23.040, opaque to the gateway
})

sub, err := gw.SubscribeMO("smsc", func(m *ss7client.Message) {
	// m.Sender: originating MSC, m.Recipient: SMSC address, m.PayloadData: SMS-SUBMIT TPDU
})

loc, err := gw.AnyTimeInterrogation(ctx, ss7client.ATIRequest{
	MSISDN:    "905321112233",
	Requested: ss7client.RequestedInfo{Location: true, State: true},
})
// loc.Info.Location.CellGlobalID, loc.Info.Location.VLRNumber, loc.Info.State.State, …

route, err := gw.SendRoutingInfo(ctx, ss7client.RoutingRequest{MSISDN: "905321112233"})
// route.Routing.RoamingNumber.Digits (MSRN), route.Routing.Forwarding, route.Routing.VMSCAddress, route.IMSI

Behaviour worth knowing

  • Correlation. Responses are broadcast on the response subject; every client instance receives every response and keeps only those carrying its own correlation IDs.

  • Failures. Every outcome comes back on the response subject as *GatewayError:

    • the peer answered with a MAP ReturnError → Status REMOTE_ERROR, Code the MAP error code (MAPErrAbsentSubscriberSM, MAPErrUnknownSubscriber, …), Message its name — the input to an SMSC's retry decision;
    • a TCAP Reject → REMOTE_ERROR with ErrCodeRemoteError;
    • the dialogue timed out or was aborted → TIMEOUT / ABORTED with a negative Code;
    • the gateway refused the request before starting a dialogue → REJECTED with ErrCodeRejected and the reason (gateway 0.7.4 and later).

    Any status the client does not recognise is treated as a failure, never as success.

  • Deadlines. Gateways before 0.7.4 send no response for a request they reject before starting a dialogue, and no gateway can answer a request that is not valid JSON. The client checks the fields the gateway requires before publishing, and bounds a request without a context deadline by DefaultTimeout (40s, longer than the gateway's default 30s TCAP dialogue timeout).

  • Access. AnyTimeInterrogation, ProvideSubscriberInfo and SendRoutingInfo return the IMSI, serving node or location of any subscriber they are asked about.

    • Grant publish rights on map.ati.request, map.psi.request and map.routing.request only to the applications that need them. The call routing subjects are outside map.sri.*, so granting SRI-for-SM does not grant them; a grant of map.*.request or map.> does.
    • Response subjects are broadcast. Subscribe rights on map.ati.response, map.psi.response or map.routing.response show every answer, every requester's — IMSIs, locations, roaming numbers.
    • A Client subscribes to an operation's response subject on its first request of that operation, so an account limited to some operations works.
  • MO delivery is a plain NATS publish: an MO-ForwardSM published while no subscriber is connected is lost. Use a queue group to share the stream across instances.

Licence

Apache License 2.0. Copyright 2026 3eAI Labs Ltd. Contributions are accepted under the 3eAI Labs Contributor Licence Agreement; see CONTRIBUTING.md.

Documentation

Overview

Package ss7client is the NATS client for ss7-3eai-gateway: the subjects, the message schema and a typed request/response client for the MAP interfaces the gateway implements.

This module is licensed under the Apache License 2.0, separately from the gateway server (AGPL-3.0-only), so an SMSC or any other application can link it without taking on the server's licence. The dependency runs one way: the server imports this module for the wire contract, this module never imports the server.

Interface covered

Only the interface the gateway implements end to end is exposed:

Wire model

Every message is a JSON-encoded Message. Requests are published on a request subject; the gateway queue-subscribes, runs the MAP dialogue and publishes the outcome — result or failure — on the matching response subject with the request's correlation_id. Response subjects are broadcast: every client instance receives every response and keeps only its own, by correlation_id. A Client subscribes to a response subject on the first request that needs it.

A request the gateway refuses before starting a dialogue — a missing or invalid field, no capacity for a new dialogue — is answered with StatusRejected from gateway 0.7.4 on; earlier gateways send nothing, and nothing can be sent for a request that is not valid JSON. Client therefore validates the fields the gateway requires before publishing, and applies a default deadline when the context has none.

Index

Constants

View Source
const (
	// SubjectATIRequest carries AnyTimeInterrogation requests, application → gateway.
	SubjectATIRequest = "map.ati.request"
	// SubjectATIResponse carries AnyTimeInterrogation results and failures, gateway → application.
	SubjectATIResponse = "map.ati.response"
	// SubjectPSIRequest carries ProvideSubscriberInfo requests, application → gateway.
	SubjectPSIRequest = "map.psi.request"
	// SubjectPSIResponse carries ProvideSubscriberInfo results and failures, gateway → application.
	SubjectPSIResponse = "map.psi.response"
)

NATS subjects of the MAP location interface (3GPP TS 29.002 §8.11).

View Source
const (
	DomainCS = "cs"
	DomainPS = "ps"
)

Domains of RequestedInfo.Domain (TS 29.002 DomainType).

View Source
const (
	// SubjectSRIRequest carries SRI-for-SM requests, application → gateway.
	SubjectSRIRequest = "map.sri.request"
	// SubjectSRIResponse carries SRI-for-SM results and failures, gateway → application.
	SubjectSRIResponse = "map.sri.response"
	// SubjectMTSMSRequest carries MT-Forward-SM requests, application → gateway.
	SubjectMTSMSRequest = "map.mt.sms.request"
	// SubjectMTSMSResponse carries MT-Forward-SM results and failures, gateway → application.
	SubjectMTSMSResponse = "map.mt.sms.response"
	// SubjectMOSMS carries MO-Forward-SM received from a foreign MSC, gateway → application.
	SubjectMOSMS = "map.mo.sms"
)

NATS subjects of the MAP SMS interface. The gateway queue-subscribes to the request subjects (queue group = its cluster name) and publishes on the response subjects.

View Source
const (
	// ParamServiceCentreAddress (request, SRI and MT): the SMSC address, as
	// a digit string or an [AddressString] object.
	ParamServiceCentreAddress = "service_centre_address"
	// ParamNetworkNodeNumber (request, MT): the serving MSC/VLR address
	// returned by SRI-for-SM, as a digit string or an [AddressString] object.
	ParamNetworkNodeNumber = "network_node_number"
	// ParamTPDUBase64 (request, MT): the TPDU as standard base64, an
	// alternative to Message.PayloadData.
	ParamTPDUBase64 = "tpdu_base64"
	// ParamVMSCAddress (response, SRI): digits of the network node number
	// returned by the HLR.
	ParamVMSCAddress = "vmsc_address"
)

Keys of Message.Parameters understood or produced by the gateway.

View Source
const (
	// StatusDelivered: MT-Forward-SM ended with a ReturnResult. A successful
	// SRI-for-SM, AnyTimeInterrogation, ProvideSubscriberInfo or
	// SendRoutingInfo response carries an empty status.
	StatusDelivered = "DELIVERED"
	// StatusTimeout: the gateway's TCAP dialogue timer expired.
	StatusTimeout = "TIMEOUT"
	// StatusAborted: the peer aborted the dialogue (TC-P-ABORT / TC-U-ABORT).
	StatusAborted = "ABORTED"
	// StatusRejected: the gateway refused the request before starting a
	// dialogue — a missing or invalid field, or no capacity for a new
	// dialogue. ErrorCode is ErrCodeRejected and ErrorMessage the reason.
	StatusRejected = "REJECTED"
	// StatusRemoteError: the peer answered with a MAP ReturnError — ErrorCode
	// is the MAP error code (positive, see MAPErr*) and ErrorMessage its name —
	// or with a TCAP Reject / a ReturnError without a code — ErrorCode is
	// ErrCodeRemoteError.
	StatusRemoteError = "REMOTE_ERROR"
)

Values of Message.Status on response subjects.

View Source
const (
	ErrCodeTimeout      int32 = -1
	ErrCodeAborted      int32 = -2
	ErrCodeRemoteError  int32 = -3
	ErrCodeRejected     int32 = -4
	ErrCodeUnclassified int32 = -99
)

Gateway-private failure codes in Message.ErrorCode. They are negative so they never collide with MAP error codes (3GPP TS 29.002 MAP-ErrorCodes, positive).

View Source
const (
	MAPErrUnknownSubscriber         int32 = 1
	MAPErrUnidentifiedSubscriber    int32 = 5
	MAPErrAbsentSubscriberSM        int32 = 6
	MAPErrIllegalSubscriber         int32 = 9
	MAPErrTeleserviceNotProvisioned int32 = 11
	MAPErrIllegalEquipment          int32 = 12
	MAPErrCallBarred                int32 = 13
	MAPErrFacilityNotSupported      int32 = 21
	MAPErrSubscriberBusyForMTSMS    int32 = 31
	MAPErrSMDeliveryFailure         int32 = 32
	MAPErrSystemFailure             int32 = 34
	MAPErrDataMissing               int32 = 35
	MAPErrUnexpectedDataValue       int32 = 36
)

MAP error codes (3GPP TS 29.002, MAP-ErrorCodes) that SendRoutingInfoForSM and MT-ForwardSM can return, carried in Message.ErrorCode with StatusRemoteError. The gateway passes any code through; these are the ones an SMSC's retry logic normally distinguishes.

View Source
const (
	// SubjectRoutingRequest carries SendRoutingInfo requests, application → gateway.
	SubjectRoutingRequest = "map.routing.request"
	// SubjectRoutingResponse carries SendRoutingInfo results and failures, gateway → application.
	SubjectRoutingResponse = "map.routing.response"
)

NATS subjects of MAP call routing (3GPP TS 29.002 §10.1, SendRoutingInfo). They are not under map.sri.*, the SRI-for-SM subjects, so that NATS permissions can grant one without the other: SendRoutingInfo returns the IMSI and the serving MSC of any subscriber it is asked about.

View Source
const (
	MAPErrBearerServiceNotProvisioned int32 = 10
	MAPErrForwardingViolation         int32 = 14
	MAPErrCUGReject                   int32 = 15
	// MAPErrAbsentSubscriber is a call's absentSubscriber, not the
	// short-message MAPErrAbsentSubscriberSM (6).
	MAPErrAbsentSubscriber int32 = 27
	MAPErrNumberChanged    int32 = 44
	// MAPErrBusySubscriber is a call's busySubscriber, not the
	// short-message MAPErrSubscriberBusyForMTSMS (31).
	MAPErrBusySubscriber    int32 = 45
	MAPErrNoSubscriberReply int32 = 46
	MAPErrORNotAllowed      int32 = 48
)

MAP error codes (TS 29.002 MAP-ErrorCodes) that SendRoutingInfo can return in addition to those with constants already: unknownSubscriber, teleserviceNotProvisioned, callBarred, facilityNotSupported, systemFailure, dataMissing, unexpectedDataValue. Error parameters (the absent subscriber's reason, the call barring cause) are not passed on.

View Source
const DefaultTimeout = 40 * time.Second

DefaultTimeout bounds a request whose context has no deadline. It is longer than the gateway's default TCAP dialogue timeout (tcap.dialogue_timeout, 30s), so the gateway's own TIMEOUT response normally arrives first.

View Source
const MAPErrATINotAllowed int32 = 49

MAPErrATINotAllowed is ati-NotAllowed (TS 29.002 MAP-ErrorCodes): the HLR does not accept AnyTimeInterrogation from this gsmSCF-Address. The other errors of ATI and PSI — systemFailure, dataMissing, unexpectedDataValue, unknownSubscriber — have MAPErr* constants already.

View Source
const (
	// ParamVLRNumber (request, PSI): the address of the VLR serving the
	// subscriber, as a digit string or an [AddressString] object.
	ParamVLRNumber = "vlr_number"
)

Keys of Message.Parameters for the location interface.

Variables

View Source
var (
	// ErrInvalidRequest wraps a request rejected before publishing because
	// a field the gateway requires is missing.
	ErrInvalidRequest = errors.New("ss7 client: invalid request")
	// ErrClosed is returned for requests made after, or pending at, Close.
	ErrClosed = errors.New("ss7 client: closed")
)

Functions

This section is empty.

Types

type ATIRequest added in v0.2.0

type ATIRequest struct {
	// Exactly one of MSISDN and IMSI (digits) identifies the subscriber.
	MSISDN string
	IMSI   string
	// Requested selects what to ask for.
	Requested RequestedInfo
	// HLRGlobalTitle and HLRPointCode address the HLR directly. Without
	// them the gateway routes on the MSISDN as global title (or uses
	// map.hlr_gt / map.hlr_pc when map.sri_routing is "hlr"); a request by
	// IMSI therefore needs one of them or map.sri_routing "hlr".
	HLRGlobalTitle string
	HLRPointCode   uint32
}

ATIRequest is a MAP AnyTimeInterrogation towards the subscriber's HLR (3GPP TS 29.002 §8.11.1).

type AddressString

type AddressString struct {
	Digits        string `json:"digits"`
	Nature        uint8  `json:"nature"`
	NumberingPlan uint8  `json:"numbering_plan"`
}

AddressString is the object form of an address parameter. Nature and NumberingPlan are the TS 29.002 AddressString nature-of-address and numbering-plan indicators, coded as there: Nature 1 = international, 2 = national significant, 4 = subscriber number (not the SCCP global title coding, where international is 4); NumberingPlan 1 = ISDN/E.164. A bare digit string in Parameters means international / ISDN-E.164.

func E164

func E164(digits string) AddressString

E164 returns an international ISDN/E.164 AddressString.

type BasicService added in v0.3.0

type BasicService struct {
	// Kind is the alternative's ASN.1 name: "ext-BearerService" or
	// "ext-Teleservice".
	Kind string `json:"kind"`
	// Code is the service code (TS 29.002 Ext-BearerServiceCode /
	// Ext-TeleserviceCode, e.g. 11 for telephony), hex.
	Code string `json:"code"`
}

BasicService is TS 29.002 Ext-BasicServiceCode.

type CAMELRouting added in v0.3.0

type CAMELRouting struct {
	Forwarding *ForwardingData `json:"forwarding,omitempty"`
	// SubscriptionInfo is the BER encoding of GmscCamelSubscriptionInfo
	// (T-CSI, O-CSI, D-CSI and their criteria), hex, tag included.
	SubscriptionInfo string `json:"subscription_info"`
}

CAMELRouting is TS 29.002 CamelRoutingInfo.

type CellGlobalID added in v0.2.0

type CellGlobalID struct {
	MCC string `json:"mcc"`
	MNC string `json:"mnc"`
	LAC uint16 `json:"lac"`
	CI  uint16 `json:"ci"`
}

CellGlobalID is a cell global identity or service area identity (TS 23.003).

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client sends MAP requests to the gateway and matches the responses by correlation ID. It is safe for concurrent use. It does not own the NATS connection: Close releases the client's subscriptions only.

func New

func New(nc *nats.Conn, opts ...Option) (*Client, error)

New returns a Client. It subscribes to an operation's response subject on the first request of that operation, not before, so that an application whose NATS account may use only some operations — the SMS subjects but not call routing, say — does not trip a permission violation on the others.

func (*Client) AnyTimeInterrogation added in v0.2.0

func (c *Client) AnyTimeInterrogation(ctx context.Context, req ATIRequest) (*SubscriberInfoResult, error)

AnyTimeInterrogation asks the subscriber's HLR for the information in req.Requested. The gsmSCF-Address the HLR screens the request on is the gateway's own (map.gsmscf_address, else its cluster GT, else its GT); a request cannot choose it, so a NATS publisher cannot present itself as another gsmSCF. On a gateway-reported failure it returns *GatewayError — with MAPErrATINotAllowed when the HLR refuses this gsmSCF.

func (*Client) Close

func (c *Client) Close() error

Close unsubscribes and fails every pending request with ErrClosed.

func (*Client) MTForwardSM

func (c *Client) MTForwardSM(ctx context.Context, req MTRequest) (*MTResult, error)

MTForwardSM delivers a short message to the serving MSC. On a gateway-reported failure it returns *GatewayError.

func (*Client) ProvideSubscriberInfo added in v0.2.0

func (c *Client) ProvideSubscriberInfo(ctx context.Context, req PSIRequest) (*SubscriberInfoResult, error)

ProvideSubscriberInfo asks the VLR serving the subscriber for the information in req.Requested. On a gateway-reported failure it returns *GatewayError.

func (*Client) SendRoutingInfo added in v0.3.0

func (c *Client) SendRoutingInfo(ctx context.Context, req RoutingRequest) (*RoutingResult, error)

SendRoutingInfo asks the subscriber's HLR how to route a basic call to req.MSISDN (interrogationType basicCall). The GMSC address the request carries is the gateway's own (its cluster GT, else its GT). It needs a gateway that serves map.routing.request (0.7.6 and later); an older one leaves the request unanswered until the deadline. On a gateway-reported failure it returns *GatewayError — MAPErrAbsentSubscriber, MAPErrBusySubscriber, MAPErrCallBarred and the like when the HLR refuses the call.

func (*Client) SendRoutingInfoForSM

func (c *Client) SendRoutingInfoForSM(ctx context.Context, req SRIRequest) (*SRIResult, error)

SendRoutingInfoForSM asks the subscriber's HLR where to deliver a short message. On a gateway-reported failure it returns *GatewayError.

func (*Client) SubscribeMO

func (c *Client) SubscribeMO(queue string, handle func(*Message)) (*nats.Subscription, error)

SubscribeMO delivers MO-Forward-SM messages the gateway received from foreign MSCs: Sender is the originating MSC address, Recipient the SMSC address, IMSI the originator when the network supplied it, PayloadData the SMS-SUBMIT TPDU. With a non-empty queue, instances sharing the queue name split the stream; with an empty queue every instance receives every message. The returned subscription is the caller's to unsubscribe.

MO is a plain NATS publish: a message published while no subscriber is connected is lost.

type Direction

type Direction string

Direction is relative to the SS7 network: Inbound goes into it (application → gateway), Outbound comes out of it (gateway → application).

const (
	DirectionInbound  Direction = "INBOUND"
	DirectionOutbound Direction = "OUTBOUND"
)

type ForwardingData added in v0.3.0

type ForwardingData struct {
	// ForwardedToNumber is the forwarded-to number (forwardedToNumber, or
	// longForwardedToNumber when the HLR sent the long form). With CAMEL
	// phase 2 an HLR may send a number that is not E.164: Nature and
	// NumberingPlan say how to read it, and non-digit TBCD values come
	// through as '*', '#', 'a', 'b', 'c'.
	ForwardedToNumber *AddressString `json:"forwarded_to_number,omitempty"`
	// ForwardedToSubaddress is the ISDN subaddress, hex.
	ForwardedToSubaddress string `json:"forwarded_to_subaddress,omitempty"`
	// Options are the ForwardingOptions, when present.
	Options *ForwardingOptions `json:"options,omitempty"`
}

ForwardingData is TS 29.002 ForwardingData.

type ForwardingOptions added in v0.3.0

type ForwardingOptions struct {
	NotifyForwardingParty   bool `json:"notify_forwarding_party,omitempty"`
	RedirectingPresentation bool `json:"redirecting_presentation,omitempty"`
	NotifyCallingParty      bool `json:"notify_calling_party,omitempty"`
	// Reason is notReachable, busy, noReply or unconditional.
	Reason string `json:"reason"`
}

ForwardingOptions is TS 29.002 ForwardingOptions, decoded.

type GatewayError

type GatewayError struct {
	CorrelationID string
	Status        string // StatusTimeout, StatusAborted, ...
	Code          int32  // ErrCode* (negative) or a MAP error code (positive, MAPErr*)
	Message       string
	NodeID        string
}

GatewayError is a failure the gateway reported on a response subject.

func (*GatewayError) Error

func (e *GatewayError) Error() string

type Location added in v0.2.0

type Location struct {
	// AgeMinutes is the time since the last contact with the subscriber:
	// 0 = in contact now, 32767 = at least that old.
	AgeMinutes *int `json:"age_minutes,omitempty"`
	// VLRNumber and MSCNumber (CS) or SGSNNumber (PS): E.164 digits.
	VLRNumber  string `json:"vlr_number,omitempty"`
	MSCNumber  string `json:"msc_number,omitempty"`
	SGSNNumber string `json:"sgsn_number,omitempty"`
	// At most one of CellGlobalID, ServiceAreaID and LocationArea is set.
	CellGlobalID  *CellGlobalID  `json:"cell_global_id,omitempty"`
	ServiceAreaID *ServiceAreaID `json:"service_area_id,omitempty"`
	LocationArea  *LocationArea  `json:"location_area,omitempty"`
	// RoutingAreaID is the RAI value part (TS 29.060), hex. PS only.
	RoutingAreaID string `json:"routing_area_id,omitempty"`
	// LocationNumber (ITU-T Q.763), hex. CS only.
	LocationNumber string `json:"location_number,omitempty"`
	// GeographicalInformation (TS 23.032 ellipsoid point with uncertainty
	// circle, 8 octets) and GeodeticInformation (Q.763, 10 octets), hex.
	GeographicalInformation string `json:"geographical_information,omitempty"`
	GeodeticInformation     string `json:"geodetic_information,omitempty"`
	// CurrentLocationRetrieved: the location was obtained by paging just now.
	CurrentLocationRetrieved bool `json:"current_location_retrieved,omitempty"`
	// EPS is the E-UTRAN location, when the HLR returned it within the CS
	// location. CS only.
	EPS *LocationEPS `json:"eps,omitempty"`
}

Location is TS 29.002 LocationInformation (CS) or LocationInformationGPRS (PS).

type LocationArea added in v0.2.0

type LocationArea struct {
	MCC string `json:"mcc"`
	MNC string `json:"mnc"`
	LAC uint16 `json:"lac"`
}

LocationArea is a location area identity (TS 23.003).

type LocationEPS added in v0.2.0

type LocationEPS struct {
	// ECGI and TAI as coded in TS 29.118, hex.
	ECGI string `json:"ecgi,omitempty"`
	TAI  string `json:"tai,omitempty"`
	// MMEName is the serving MME's Diameter identity.
	MMEName                  string `json:"mme_name,omitempty"`
	AgeMinutes               *int   `json:"age_minutes,omitempty"`
	GeographicalInformation  string `json:"geographical_information,omitempty"`
	GeodeticInformation      string `json:"geodetic_information,omitempty"`
	CurrentLocationRetrieved bool   `json:"current_location_retrieved,omitempty"`
}

LocationEPS is TS 29.002 LocationInformationEPS.

type MNPInfo added in v0.2.0

type MNPInfo struct {
	RouteingNumber string `json:"routeing_number,omitempty"`
	IMSI           string `json:"imsi,omitempty"`
	MSISDN         string `json:"msisdn,omitempty"`
	// Status is the NumberPortabilityStatus name: notKnownToBePorted,
	// ownNumberPortedOut, foreignNumberPortedToForeignNetwork,
	// ownNumberNotPortedOut, foreignNumberPortedIn.
	Status string `json:"status,omitempty"`
}

MNPInfo is TS 29.002 MNPInfoRes.

type MTRequest

type MTRequest struct {
	IMSI                 string        // required, from SRIResult.IMSI
	NetworkNodeNumber    AddressString // required, from SRIResult.NetworkNodeNumber
	ServiceCentreAddress AddressString // required
	TPDU                 []byte        // required, SMS-DELIVER TPDU (3GPP TS 23.040), opaque to the gateway
	// MSCPointCode overrides the destination point code. Zero routes on the
	// network node number GT alone.
	MSCPointCode uint32
}

MTRequest is a MAP MT-ForwardSM request (3GPP TS 29.002 §12.9).

type MTResult

type MTResult struct {
	Status string // StatusDelivered
	NodeID string
	Raw    *Message
}

MTResult is a successful MT-ForwardSM answer.

type Message

type Message struct {
	MessageID     string      `json:"message_id"`
	CorrelationID string      `json:"correlation_id,omitempty"`
	MessageType   MessageType `json:"message_type"`
	Direction     Direction   `json:"direction"`
	Timestamp     time.Time   `json:"timestamp"`

	// Addressing (E.164 digits).
	Sender    string `json:"sender,omitempty"`
	Recipient string `json:"recipient,omitempty"`
	IMSI      string `json:"imsi,omitempty"`
	MSISDN    string `json:"msisdn,omitempty"`

	// SS7 routing overrides. Zero/empty means "use the gateway's configuration".
	OPC         uint32 `json:"opc,omitempty"`
	DPC         uint32 `json:"dpc,omitempty"`
	SSN         uint8  `json:"ssn,omitempty"`
	GlobalTitle string `json:"global_title,omitempty"`

	Content     string                 `json:"content,omitempty"`
	PayloadData []byte                 `json:"payload_data,omitempty"` // base64 in JSON
	Parameters  map[string]interface{} `json:"parameters,omitempty"`

	ServiceKey uint32 `json:"service_key,omitempty"`
	EventType  string `json:"event_type,omitempty"`

	// Location interface (map.ati.*, map.psi.*): what a request asks for
	// and what the answer carries. SubscriberInfo is also in a call routing
	// answer when the HLR returns the subscriber's location or state.
	RequestedInfo  *RequestedInfo  `json:"requested_info,omitempty"`
	SubscriberInfo *SubscriberInfo `json:"subscriber_info,omitempty"`

	// Call routing (map.routing.*): the answer's routing information. The
	// answer's IMSI is in IMSI, its location and state, if any, in
	// SubscriberInfo.
	RoutingInfo *RoutingInfo `json:"routing_info,omitempty"`

	Status       string `json:"status,omitempty"`
	ErrorCode    int32  `json:"error_code,omitempty"`
	ErrorMessage string `json:"error_message,omitempty"`

	TraceID string `json:"trace_id,omitempty"`
	NodeID  string `json:"node_id,omitempty"` // gateway node that handled the dialogue
}

Message is the JSON document carried on every subject. Field names and JSON tags are the wire contract shared with non-Go consumers; changing one breaks them.

type MessageType

type MessageType string

MessageType identifies the operation a Message belongs to.

const (
	MsgTypeMAPATI MessageType = "MAP_ATI"
	MsgTypeMAPPSI MessageType = "MAP_PSI"
)
const (
	MsgTypeMAPSRI   MessageType = "MAP_SRI"
	MsgTypeMAPMTSMS MessageType = "MAP_MT_SMS"
	MsgTypeMAPMOSMS MessageType = "MAP_MO_SMS"
)
const MsgTypeMAPRouting MessageType = "MAP_ROUTING"

MsgTypeMAPRouting requests carry msisdn and, optionally, global_title and dpc (the HLR's address). The gateway ignores every other request field — opc, ssn, sender, recipient, parameters: the SendRoutingInfo it sends is a basic call interrogation whose GMSC address is its own.

type Option

type Option func(*Client)

Option configures a Client.

func WithDecodeErrorHandler

func WithDecodeErrorHandler(f func(subject string, data []byte, err error)) Option

WithDecodeErrorHandler receives messages on the client's subscriptions that are not valid JSON Messages. Without it they are dropped.

func WithDefaultTimeout

func WithDefaultTimeout(d time.Duration) Option

WithDefaultTimeout replaces DefaultTimeout for requests without a deadline.

type PSIRequest added in v0.2.0

type PSIRequest struct {
	IMSI string // required
	// VLRNumber is the serving VLR's address (required). For a combined
	// MSC/VLR it is normally the network node number SendRoutingInfoForSM
	// returned.
	VLRNumber AddressString
	// Requested selects what to ask for. MNP is not available here.
	Requested RequestedInfo
	// VLRPointCode routes on point code instead of the VLR number GT.
	VLRPointCode uint32
}

PSIRequest is a MAP ProvideSubscriberInfo towards the VLR serving the subscriber (3GPP TS 29.002 §8.11.2).

type RequestedInfo added in v0.2.0

type RequestedInfo struct {
	// Location asks for the location information of Domain.
	Location bool `json:"location,omitempty"`
	// CurrentLocation asks the serving node to page the subscriber for an
	// up-to-date location instead of the last known one. Requires Location.
	CurrentLocation bool `json:"current_location,omitempty"`
	// EPSLocation tells the HLR that the E-UTRAN location may be returned,
	// in Location.EPS or in SubscriberInfo.LocationEPS. Requires Location.
	EPSLocation bool `json:"eps_location,omitempty"`
	// State asks for the subscriber state of Domain.
	State bool `json:"state,omitempty"`
	// Domain is DomainCS (the default when empty) or DomainPS.
	Domain string `json:"domain,omitempty"`
	// IMEI asks for the equipment identity.
	IMEI bool `json:"imei,omitempty"`
	// MSClassmark asks for MS Classmark 2, returned for the CS domain.
	MSClassmark bool `json:"ms_classmark,omitempty"`
	// MNP asks for number portability information. AnyTimeInterrogation only.
	MNP bool `json:"mnp,omitempty"`
}

RequestedInfo selects what an AnyTimeInterrogation or ProvideSubscriberInfo asks for (TS 29.002 RequestedInfo). At least one item must be set.

type RoutingInfo added in v0.3.0

type RoutingInfo struct {
	// RoamingNumber is the MSRN to route the call on. From a number
	// portability database it is the routing number followed by the MSISDN,
	// or the MSISDN alone.
	RoamingNumber *AddressString `json:"roaming_number,omitempty"`
	// Forwarding: the call is to be forwarded.
	Forwarding *ForwardingData `json:"forwarding,omitempty"`
	// CAMEL: the subscriber has terminating CAMEL services the GMSC is to
	// invoke before routing. The gateway does not ask for them (it does not
	// offer CAMEL support in the request), so an HLR should not return this.
	CAMEL *CAMELRouting `json:"camel,omitempty"`
	// VMSCAddress is the E.164 address of the MSC serving the subscriber,
	// digits only (as Location.VLRNumber).
	VMSCAddress string `json:"vmsc_address,omitempty"`
	// MSISDN is the subscriber's basic MSISDN, when the HLR returns it.
	MSISDN string `json:"msisdn,omitempty"`
	// ForwardingInterrogationRequired: the HLR asks the GMSC to interrogate
	// it again, for forwarding, if the call is later forwarded.
	ForwardingInterrogationRequired bool `json:"forwarding_interrogation_required,omitempty"`
	// NumberPortabilityStatus is the TS 29.002 NumberPortabilityStatus name:
	// notKnownToBePorted, ownNumberPortedOut or foreignNumberPortedToForeignNetwork.
	NumberPortabilityStatus string `json:"number_portability_status,omitempty"`
	// BasicService is the service the HLR resolved the call to.
	BasicService *BasicService `json:"basic_service,omitempty"`
	// SSCodes are the supplementary services active for the call (TS 29.002
	// SS-Code, one octet each), hex.
	SSCodes []string `json:"ss_codes,omitempty"`
}

RoutingInfo is the routing part of a SendRoutingInfo answer (TS 29.002 SendRoutingInfoRes). The IMSI is in Message.IMSI and, when the HLR returns it, the subscriber's location and state in Message.SubscriberInfo. At most one of RoamingNumber, Forwarding and CAMEL is set.

type RoutingRequest added in v0.3.0

type RoutingRequest struct {
	MSISDN string // required, E.164 digits
	// HLRGlobalTitle and HLRPointCode address the HLR directly. Without
	// them the gateway routes on the MSISDN as global title (or uses
	// map.hlr_gt / map.hlr_pc when map.sri_routing is "hlr").
	HLRGlobalTitle string
	HLRPointCode   uint32
}

RoutingRequest is a MAP SendRoutingInfo towards the subscriber's HLR (3GPP TS 29.002 §10.1), with the gateway as GMSC.

type RoutingResult added in v0.3.0

type RoutingResult struct {
	IMSI    string       // the subscriber's IMSI; empty if the HLR left it out
	Routing *RoutingInfo // never nil
	// SubscriberInfo is the location and state the HLR returned, if any.
	SubscriberInfo *SubscriberInfo
	NodeID         string // gateway node that ran the dialogue
	Raw            *Message
}

RoutingResult is a successful SendRoutingInfo answer.

type SRIRequest

type SRIRequest struct {
	MSISDN               string        // required, E.164 digits
	ServiceCentreAddress AddressString // required
	// HLRGlobalTitle and HLRPointCode override the gateway's map.hlr_gt and
	// map.hlr_pc for this request. Leave empty to use the configuration.
	HLRGlobalTitle string
	HLRPointCode   uint32
}

SRIRequest is a MAP SendRoutingInfoForSM request (3GPP TS 29.002 §12.1).

type SRIResult

type SRIResult struct {
	IMSI string
	// NetworkNodeNumber is the serving MSC/VLR address digits; pass it to
	// MTRequest.NetworkNodeNumber.
	NetworkNodeNumber string
	NodeID            string // gateway node that ran the dialogue
	Raw               *Message
}

SRIResult is a successful SendRoutingInfoForSM answer.

type ServiceAreaID added in v0.2.0

type ServiceAreaID struct {
	MCC string `json:"mcc"`
	MNC string `json:"mnc"`
	LAC uint16 `json:"lac"`
	SAC uint16 `json:"sac"`
}

ServiceAreaID is a service area identity (TS 23.003): SAC is the service area code.

type SubscriberInfo added in v0.2.0

type SubscriberInfo struct {
	// Location is the circuit-switched location (MSC/VLR).
	Location *Location `json:"location,omitempty"`
	// State is the circuit-switched subscriber state.
	State *SubscriberState `json:"state,omitempty"`
	// LocationGPRS is the packet-switched location (SGSN).
	LocationGPRS *Location `json:"location_gprs,omitempty"`
	// PSState is the packet-switched subscriber state.
	PSState *SubscriberState `json:"ps_state,omitempty"`
	// EPSState is the EPS subscriber state.
	EPSState *SubscriberState `json:"eps_state,omitempty"`
	// LocationEPS is the EPS location returned outside Location.
	LocationEPS *LocationEPS `json:"location_eps,omitempty"`
	// IMEI digits (TS 23.003), 15 or 16 of them.
	IMEI string `json:"imei,omitempty"`
	// MSClassmark2 is the value part of the MS Classmark 2 IE (TS 24.008), hex.
	MSClassmark2 string `json:"ms_classmark2,omitempty"`
	// MNP is the number portability information.
	MNP *MNPInfo `json:"mnp,omitempty"`
}

SubscriberInfo is the answer to an AnyTimeInterrogation or a ProvideSubscriberInfo (TS 29.002 SubscriberInfo): only what was requested and what the network knows is present. Octet strings whose layout another specification defines are passed through as lowercase hex.

type SubscriberInfoResult added in v0.2.0

type SubscriberInfoResult struct {
	Info   *SubscriberInfo // never nil
	NodeID string          // gateway node that ran the dialogue
	Raw    *Message
}

SubscriberInfoResult is a successful AnyTimeInterrogation or ProvideSubscriberInfo answer.

type SubscriberState added in v0.2.0

type SubscriberState struct {
	State              string `json:"state"`
	NotReachableReason string `json:"not_reachable_reason,omitempty"`
}

SubscriberState is TS 29.002 SubscriberState (CS) or PS-SubscriberState (PS, EPS). State is the ASN.1 name of the alternative:

  • CS: assumedIdle, camelBusy, netDetNotReachable, notProvidedFromVLR;
  • PS/EPS: notProvidedFromSGSNorMME, ps-Detached, ps-AttachedNotReachableForPaging, ps-AttachedReachableForPaging, ps-PDP-ActiveNotReachableForPaging, ps-PDP-ActiveReachableForPaging, netDetNotReachable.

NotReachableReason accompanies netDetNotReachable: msPurged, imsiDetached, restrictedArea or notRegistered.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL